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:

  1. Prepare your environment
  2. Get prerequisites
  3. Download the sample
  4. Build and run the sample
  5. Host the sample app
  6. Update the credentials for your hosted app
  7. 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.

Get prerequisites

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

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

Note

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

Tip

You can fork this repo to modify and save your changes to GitHub.

Build and run the sample

You can build and run the smaple after it is cloned.

To build and run the cloned sample

  1. Open the solution file Microsoft.Teams.Samples.HelloWorld.sln from the Microsoft-Teams-Samples/samples/app-hello-world/csharp directory of the sample.

  2. Select Build Solution from the Build menu.

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

    • https://localhost:44327/
    • https://localhost:44327/hello
    • https://localhost:44327/first
    • https://localhost:44327/second

    Note

    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 https://yourteamsapp.ngrok.io or https://yourteamsapp.azurewebsites.net.

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

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

  1. Open your browser and go to https://d0ac14a5.ngrok.io/hello. This will load your app's Hello page.

  2. Instead of the URL mentioned in Step 1, use the forwarding address displayed by ngrok in your console session.

    Note

    If you have used a different port in the build and run step, ensure 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. This is done to keep ngrok from running without interfering with the app. You have to stop, rebuild, and rerun the app. The ngrok session 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 ngrok does 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:

Visual Studio

Update the app package

Use App Studio to update the app package

Tip

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:

  1. To install App Studio in Teams, select the Apps icon at the bottom of the left-hand bar, and search for App Studio:

    Finding App Studio in the Store View
  2. Select the App Studio tile and choose Install. The App Studio is installed:

    Installing App Studio
  3. To create the app package for your Teams app, select the Manifest editor tab in App Studio:

    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 gulp at 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:

    Build the app package on .NET with Visual Studio

    You can build the app package on Node.js 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.

  4. Now to modify this app package, select Import an existing app in the Manifest editor:

    Importing an existing app
  5. Select the Hello World tile for your newly imported app:

    Newly imported app view

    The following image shows the imported app package in App Studio:

    Importing the app package

    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.

App details

Select App details under Details. Select the Generate button to create a new App ID.

Your new App ID is similar to 2322041b-72bf-459d-b107-f4f335bc35bd.

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.

Tabs

It is simple to add tabs to a Teams app. The sample app already supports several tabs, and you can enable them.

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 is displayed. Select the ... symbol of the Tab configuration url and choose Edit from the drop-down menu. Change the URL to https://yourteamsapp.ngrok.io/configure where yourteamsapp.ngrok.io must be replaced with the URL that you used when hosting your app.

Personal tabs

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:

Adding a personal tab dialog

Update the following boxes with your app URL:

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

Replace yourteamsapp.ngrok.io by the URL that you used when hosting your app.

Bots

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:

Adding a bot

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.

Note

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:

  1. Select Delete next to the imported bot in the bot list. Now there are no bots left to show.

  2. Select Setup to display the Set up a bot dialog box.

    Adding a bot dialog
  3. Add a bot name Contoso bot and select all three check boxes under Scope.

  4. Choose Save to exit the dialog box. App Studio registers your bot with Microsoft and displays your new bot in the bot list.

  5. Now open a text file in notepad and copy and paste your new bot ID into it.

  6. Click Generate New Password, and note the password in the same text file you noted your bot App ID.

  7. Update the Bot endpoint address to https://yourteamsapp.ngrok.io/api/messages, and replace yourteamsapp.ngrok.io with the URL that you used when hosting your app.

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

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:

  1. Select Messaging extensions under Capabilities in the left-hand pane of App Studio to configure the messaging extension:

    Adding a messaging extension

    The sample messaging extension is listed in the Messaging Extensions pane.

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

  3. Select the Use existing bot tab and Select from one of my existing bots.

  4. Select the bot you created from the drop-down menu. Add a Bot name and select Save to close the dialog box.

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

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

    Under Parameter:

    • Name: Enter the parameter name
    • Title: Enter the card title
    • Description: Enter card description
  7. 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:

  1. Use Test and distribute of App Studio to install your app in Teams.

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

  3. Select Test and distribute under Finish in the left-hand pane of App Studio:

    Testing your app
  4. To upload your app to Teams, select the Install button under Test and Distribute:

    Adding a messaging extension dialog

    Note

    If you are unable to sideload the app, verify whether you have enabled custom app uploading.

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

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

    The finished app

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

  1. Open the appsettings.json file.

  2. Update the MicrosoftAppId value with your bot ID that you saved in the text file.

  3. Update the MicrosoftAppPassword with the bot password that you saved.

    Setting the keys

    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

  1. Go to a channel in the team where you installed the sample app and select the '+' button to add a new tab.

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

  3. Select Save. The Hello World tab is loaded with the tab.

    Screenshot of configure

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.

    Bot responses

Test your messaging extension

To test your messaging extension

  1. Select ... below the input box in your conversation view. A menu with the 'Hello World' app is displayed.

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

    Messaging extension menu Messaging extension result
  3. Select one of the random text. A card formatted and ready to send with your own message is shown.

    Messaging extension send

See also