Build your first Teams app using C#
In this tutorial, you will learn how to build your very first Microsoft Teams app using .NET or C#. It also walks you through the steps to:
- Prepare your environment
- Get prerequisites
- Download the sample
- Build and run the sample
- Host the sample app
- Update the credentials for your hosted app
- Configure the app tab
Prepare your development environment
Before you begin, you must prepare your development environment. Custom app uploading must be enabled for the Office 365 organization where you want to build your app. If you need a dedicated development tenant, you can sign up for the Office 365 developer program. For more information, see setup your development environment.
To complete this tutorial, you need to install the following tools:
You can install the free community edition of Visual Studio. During installation, if there is an option to add
git to the path, select it. In a terminal window, run the following command to verify your
$ git --version git version 2.17.1.windows.2
Use a suitable terminal window on your platform. These examples use Git Bash but can be run on most platforms.
Open the latest version of Visual Studio and install any updates.
You can use the same terminal window to run the commands in this tutorial.
Download the sample
You can get started with a simple Hello, World! sample in C#. In a terminal window, run the following command to clone the sample repository to your computer:
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
Build and run the sample
You can build and run the smaple after it is cloned.
To build and run the cloned sample
Open the solution file Microsoft.Teams.Samples.HelloWorld.sln from the Microsoft-Teams-Samples/samples/app-hello-world/csharp directory of the sample.
Select Build Solution from the Build menu.
Select the F5 key, or select Start Debugging from the Debug menu to run the sample.
When the app starts, a browser window opens with the root of the app launched. You can go to the following URLs to verify that all the app URLs are loading:
If you receive an error
Could not find a part of the path … bin\roslyn\csc.exe, update the package with the command
Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r. For more information, see this question on Stack Overflow.
Deploy your sample app
Apps in Microsoft Teams are web applications that provide one or more capabilities. For the Teams platform to load your app, your app must be available on the internet. To do this, 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 computer using
ngrok. After you host your app, make a note of its root URL, such as
Tunnel using ngrok
For quick testing, you can run the app on your computer and create a tunnel to it through a web endpoint.
ngrok is a free tool with which you can get a web address, such as
https://d0ac14a5.ngrok.io. You can download and install ngrok and add it to a location in your
After you install
ngrok, open a new terminal window and run the following command to create a tunnel:
ngrok http 44327 -host-header=localhost:44327
Ngrok responds to requests from the internet and routes them to your app running on port 44327.
To verify the response
Open your browser and go to
https://d0ac14a5.ngrok.io/hello. This will load your app's Hello page.
Instead of the URL mentioned in Step 1, use the forwarding address displayed by
ngrokin your console session.
If you have used a different port in the build and run step, ensure you use the same port number to setup the
It is a good idea to run
ngrokin a different terminal window. This is done to keep
ngrokfrom running without interfering with the app. You have to stop, rebuild, and rerun the app. The
ngroksession provides useful debugging information in this window.
The app is only available during the current session on your computer. If the machine is shut down or goes to sleep, the service is no longer available. Remember this when you share the app for testing to other users. If you have to restart the service, the app returns a new address and you must update every location that uses that address. The paid version of
ngrokdoes not have this limitation.
Host in Azure
Microsoft Azure hosts your .NET application on a free tier using shared infrastructure. This is sufficient to run the
Hello World sample. For more information, see creating a new free Azure account.
Visual Studio has built-in support for app deployment to different providers, including Azure:
Update the app package
Use App Studio to update the app package
Try the Developer Portal: App Studio will soon be depricated. Configure, distribute, and manage your Teams apps with the new Developer Portal.
App Studio is a Teams app that you can install from the Teams store. It simplifies the creation and registration of an app.
Complete the following steps to update the app package:
To install App Studio in Teams, select the Apps icon at the bottom of the left-hand bar, and search for App Studio:
Select the App Studio tile and choose Install. The App Studio is installed:
To create the app package for your Teams app, select the Manifest editor tab in App Studio:
The sample comes with its own manifest and is designed to build an app package when the project is built. On .NET, the manifest.json file can be located in Visual Studio in Manifest under
Microsoft.Teams.Samples.HelloWorld.Web. On Node.js, this is done by typing
gulpat the command line in the root directory of the project.
In Visual Studio, the manifest.json file is located in under Manifest in
Microsoft.Teams.Samples.HelloWorld.Web. This step is described by the following image:
You can build the app package on Node.js by typing
gulpat 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.
Now to modify this app package, select Import an existing app in the Manifest editor:
Select the Hello World tile for your newly imported app:
The following image shows the imported app package in App Studio:
On the left-hand side of the Manifest editor there is a list of steps. On the right-hand side there is a list of properties that need to be filled in for each step. As you started with a sample app, much of the information is already completed. The next steps enable you to update the properties of the Hello World app.
Select App details under Details. Select the Generate button to create a new App ID.
Your new App ID is similar to
Go through the app details in the right-hand pane including Developer information and Branding details. These details are important if you are writing a new app for distribution.
It is simple to add tabs to a Teams app. The sample app already supports several tabs, and you can enable them.
Your app can only have one Team tab:
In this sample, the Team tab is where your configuration page is displayed. Select the ... symbol of the Tab configuration url and choose Edit from the drop-down menu. Change the URL to
yourteamsapp.ngrok.io must be replaced with the URL that you used when hosting your app.
Your app can have up to 16 tabs, including the Team tab.
Personal tabs are different from the Team tab. Hello Tab is already listed in the personal tabs list with a placeholder value
com.contoso.helloworld.hellotab. Select the ... symbol of the Tab configuration url and choose Edit from the drop-down menu. The following dialog box appears:
Update the following boxes with your app URL:
- Change the Content URL box to
- Change the Website URL box to
yourteamsapp.ngrok.io by the URL that you used when hosting your app.
It is easy to add the bots functionality to your app. The Hello World sample app already has a bot as part of the sample, but you must register it with Microsoft:
The bot that was imported from the sample does not have an associated App ID. You must create a new bot so that App Studio can create a new App ID and register it with Microsoft.
The App ID created by App Studio for the bot is different from the App ID created for the app. Each bot in an app requires its own App ID.
Complete the following steps to setup your bot:
Select Delete next to the imported bot in the bot list. Now there are no bots left to show.
Select Setup to display the Set up a bot dialog box.
Add a bot name Contoso bot and select all three check boxes under Scope.
Choose Save to exit the dialog box. App Studio registers your bot with Microsoft and displays your new bot in the bot list.
Now open a text file in notepad and copy and paste your new bot ID into it.
Click Generate New Password, and note the password in the same text file you noted your bot App ID.
Update the Bot endpoint address to
https://yourteamsapp.ngrok.io/api/messages, and replace
yourteamsapp.ngrok.iowith the URL that you used when hosting your app.
Now save your text file as you must add the information from the file to your hosted app to allow secure communication with your bot.
Messaging extensions let users ask for information from your service and post that information. The information is posted in the form of cards into the channel conversation. Messaging extensions appear at the bottom of the compose box.
Complete the following steps to setup your messaging extension:
Select Messaging extensions under Capabilities in the left-hand pane of App Studio to configure the messaging extension:
The sample messaging extension is listed in the Messaging Extensions pane.
Select Delete to remove the messaging extension, select Set up, and follow the same steps used for bots. The Messaging Extension dialog box is displayed.
Select the Use existing bot tab and Select from one of my existing bots.
Select the bot you created from the drop-down menu. Add a Bot name and select Save to close the dialog box.
Under the Command section, select Add. To add a search-based command, select the Allow users to query your service for information and insert that into a message option.
In the New command dialog box, enter the following values:
Under New command:
- Command ID: Enter random text
- Title: Enter random title
- Description: Enter random description
- Name: Enter the parameter name
- Title: Enter the card title
- Description: Enter card description
After you enter the information, select Save to close the dialog box.
Register your app in Teams
After entering the details of your app, complete the following steps to register your app in Teams:
Use Test and distribute of App Studio to install your app in Teams.
Update your hosted application with the App ID and password for your bot. For the sample app, use the same App ID and password for both bot and messaging extension.
Select Test and distribute under Finish in the left-hand pane of App Studio:
To upload your app to Teams, select the Install button under Test and Distribute:
If you are unable to sideload the app, verify whether you have enabled custom app uploading.
Select the Search box in the Add to a team section and select a team to add the sample app. You can set up a special team for testing.
Select the Install button at the bottom of the dialog box.
Your app is now available in Teams. However, the bot and the messaging extension will not work until you update the hosted applications environment with the App IDs and passwords.
Update the credentials for your hosted app
The sample app requires the environment variables to be set to the values that you saved in the text file.
To update the credentials for your hosted app
Update the MicrosoftAppId value with your bot ID that you saved in the text file.
Update the MicrosoftAppPassword with the bot password that you saved.
After 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
After you have installed the app into teams, you must configure it to display the content.
To configure the app tab
Go to a channel in the team where you installed the sample app and select the '+' button to add a new tab.
Select Hello World from the Add a tab list. A configuration dialog box is displayed that enables you to select the tab to display in this channel.
Select Save. The
Hello Worldtab is loaded with the tab.
Test your bot in Teams
You can now test the bot in Teams.
To test your bot
Select a channel in the team where you registered your app and type
@your-bot-name. This is called an @mention. The bot replies to any message that you send.
Test your messaging extension
To test your messaging extension
Select ... below the input box in your conversation view. A menu with the 'Hello World' app is displayed.
Select the menu, a set of random texts is displayed. You can select one of the random text and that is inserted into your conversation.
Select one of the random text. A card formatted and ready to send with your own message is shown.