Build your first app using C#

Cikk
Developer (Beginner)
5 minutes to complete

Start Microsoft Teams app development by building your first app with a tab, a bot, and a message extension capability.

This app will have all capabilities and each has its own UI and UX:

Diagram showing this app has three features.

In this tutorial, you'll learn:

How to set up a new project.
How to build three apps with a different capability each—tab, bot, and message extension using C# and Visual Studio 2019.
How to deploy your app from Developer Portal.

Prerequisites

4 minutes remaining

Here's a list of tools you'll need to install for building and deploying a Teams app.

	Install	For using...
Required
	Visual Studio 2019 Install one of the following two workloads: • ASP.NET and web development • .NET Core cross-platform development	.NET. You can install the free community edition of Visual Studio 2019, and install the workloads also.
	Git	Git to use the Sample C# app repo from GitHub.
	ngrok	Teams app features (conversational bot and message extension) require inbound connections. You need to expose your development system to Teams through a tunnel. A tunnel is not required for apps that only include tabs. This package is installed within the project directory (using npm `devDependencies`).
	Teams Toolkit	A Visual Studio 2019 extension that creates a project scaffolding for your app. Use latest version.
	Developer Portal for Teams	Web-based portal to configure, manage, and distribute your Teams app including to your organization or the Teams store.
	Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, call - all in one place.
Optional
	Azure Tools for Visual Studio Code and Microsoft Azure CLI	Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.

Verify git installation

If Visual Studio installation prompts you to add git to the path, select it.

To verify the version of git installed:

Open a terminal window.
Run the following command to verify the git version installed on your machine:
```
$ git --version
```
Output example: git version 2.17.1.windows.2

Install Teams Toolkit

Teams Toolkit helps simplify the development process with tools to create a project scaffolding for your app. It creates the necessary directory structure for all selected capabilities with the required files in place, ready to build the project.

Teams Toolkit is available as a Visual Studio 2019 extension.

To install Teams Toolkit extension:

Open Visual Studio 2019 and select the Extensions > Manage Extensions.
In the search box, enter Teams Toolkit.
Select Download next to the Teams Toolkit.

The changes are available after you close Visual Studio 2019. It's required as Visual Studio 2019 must restart after the installing the extension.
Select Close.
Close Visual Studio 2019.

The VSIX installer opens with instructions for installing the extension.
Follow the instructions of VSIX installer to complete the installation of the toolkit.
Open Visual Studio 2019 again.

The Teams Apps will be available as a template in Visual Studio 2019.

You also can find the Teams Toolkit on the Visual Studio Code Marketplace.

Set up your Teams development tenant

A tenant is like a space, or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where you sideload and test your app. Let's verify if you're ready to develop with the tenant.

Check for sideloading option

After creating the app, you must load your app in Teams without distributing it. This process is known as sideloading. Sign in to your Microsoft 365 account to view this option.

Note

Sideloading is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you will not be able to preview and test your app in Teams locally.

Do you already have a tenant, and do you have the admin access? Let's check if you really do!

Verify if you can sideload apps in Teams:

In the Teams client, select Store icon.
Select Manage your apps.
Look for the option to Upload a custom app. If you see the option, sideloading apps is enabled.

Note

If Teams doesn't show the option to upload a custom app, talk to your Teams administrator.

Create a free Teams developer tenant (optional)

If you don't have a Teams account, you can get it free. Join the Microsoft 365 developer program!

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears:
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Get a free Azure account

If you wish to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.

Now you've got all tools and set up your accounts. Next, let's set up your development environment and start building!

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

For this tutorial, use the Hello, World! sample in C#. You can download and clone it from GitHub.

To use this sample, clone the sample repo in one of the following ways:

Using Git Bash
Using Visual Studio 2019

To use Git Bash to clone the sample repo

Run the following command in a terminal window to clone the sample repository to your computer:
```
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
```
The sample repo for C# app is cloned on your computer in the default location.

Tip

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

You can view the cloned repository by opening it in Visual Studio 2019.

To use Visual Studio 2019 to clone the sample repo

Open Visual Studio 2019.
Select Clone a repository.
Enter https://github.com/OfficeDev/Microsoft-Teams-Samples.git as path for cloning the repo:
Enter the location where you want to clone the repo, and select Clone.

The sample repo is cloned, and Visual Studio opens. You can view the cloned repo in the Solution Explorer.

Now that you've got the sample repo cloned, let's build your first C# app for Teams.

Build and run your first C# app

3 minutes remaining

After you've cloned the repo for C# sample app, you can build and run the app in your local environment.

In this page, you'll learn to:

Build your first app
Deploy your sample app locally

Build your first app

You can view the project structure in the Solution Explorer after the workspace is created. Now, you're to build and run your app.

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 the Project menu, and select Microsoft.Teams.Samples.HelloWorld.Web Properties.
Select Debug from the left pane of the Properties window.
Move through the screen to view the Web Server Settings.
Make the following settings in Debug pane:
- Set App URL to http://localhost:3333/.
- Clear Enable SSL.
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. It shows the root of your app. You can go to the following URLs to verify that all the app URLs are loading:
- https://localhost:3333/
- https://localhost:3333/hello
- https://localhost:3333/first
- https://localhost:3333/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.

Deploy your sample app locally

Microsoft Teams apps are web applications that provide one or more capabilities. Make your app available on the internet so that the Teams platform can load it. Host your app using ngrok to create a tunnel to the local process on your computer.

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

After you install ngrok, you can create a tunnel to deploy your app locally:

Open a new terminal window.
Run the following command to create a tunnel. The sample app uses port 3333.
```
ngrok http 3333 -host-header=localhost:3333
```
The ngrok tunnel is created. Here's an example:

You can try adding hello, first, or second to the ngrok tunnel url to view different tab pages of the app.

Ngrok listens to requests from the internet and routes them to your app running on port 3333.

To verify the app's local deployment:

Open the browser.
Load your app using the following URL:

https://<forwarding address in ngrok console session>/

Here's an example of the URL:
Make a note of the forwarding address in ngrok console. You need this URL to deploy your app in Teams.

Note

If you've used a different port during build, ensure you use the same port number to setup the ngrok tunnel.

Tip

It's a good idea to run ngrok in a different terminal window. It helps to keep ngrok from interfering with the app, when you'll need to stop, rebuild, and rerun the app. The ngrok session provides useful debugging information in this window.

Important

If you use the free version of ngrok, your app will be available only during the current session on your development machine. It isn't available if the machine is shut down or goes to sleep. When you restart the service, it returns a new address. Then, you must update every location that uses the outdated address. Remember this step when sharing the app for testing.

Configure your first C# app using Developer Portal

2 minutes remaining

You can use Developer Portal to upload the app package to Teams and configure app capabilities. Developer Portal is a Teams app that simplifies the creation and registration of an app. Install from the Teams store!

After you build and test your Teams app, you can configure and preview it using Developer Portal.

In this page, you'll learn to configure the app package in Developer Portal.

Publish option in Visual Studio 2019

This tutorial uses Developer Portal to configure app capabilities and publish your app.

However, Visual Studio 2019 has built-in support for app deployment to different providers, including Azure:

Image showing the Publish to Azure menu item in Visual Studio 2019

Microsoft Azure hosts your .NET application on a free tier. It uses shared infrastructure that is sufficient to run the Hello World sample. For more information, see creating a new free Azure account.

If you use this option, you can enter the details of the Azure site and Azure resources and publish your app.

For this tutorial, you do not need to use this step.

Configure the app package in Developer Portal

You can use Developer Portal to configure the app package and its capabilities. Developer Portal is a Teams app that simplifies the creation and registration of an app. Install from the Teams store!

Configuring the app package includes:

Importing the app package to Developer Portal
Configuring app capabilities

Import the app package in Developer Portal

To import the app package:

Open Microsoft Teams.
Select the Store icon from the left-hand bar.
Search for Developer Portal in the search bar, and select Developer Portal.
Select Open.

The Developer Portal opens.
Select the Apps tab.
Select Import app.
Select the app package helloworldapp.zip from the following path in your C# sample repo directory structure:

<path to cloned C# repo>/Source/Repos/Microsoft-Teams-Samples/samples/app-hello-world/csharp/Microsoft.Teams.Samples.HelloWorld.Web/bin/Debug/netcoreapp3.1

The Hello World app is imported in Developer Portal.

Take a tour of your app in Developer Portal

After you've imported your app to Developer Portal, you can view its details, including the manifest file.

View app information

Select Basic Information from the left pane of Developer Portal.
Note the following information from the basic information:
- App ID
- Developer Information
- App URLs
Select Branding from the left pane to view the branding information.

These details are important if you are writing a new app for distribution.

View app features

Select App features from the left pane of Developer Portal.

The App features appear in the right pane. You can view cards for Personal app, Bot, and Message Extension.

View the app manifest

You use the manifest file to configure capabilities, required resources, and other important attributes for your app.

To view the app manifest:

Select Publish from the left panel to open the dropdown list, and then select App package.

The manifest file appears on the right pane.

Configure your app capabilities

After you've imported your app into Developer Portal, the next step is to configure app capabilities. Developer Portal contains all the app information in different sections. It makes configuring the app capabilities easy.

Using Developer Portal, you can:

Configure personal tab app
Configure bot
Configure message extension

Configure personal tab app

To configure personal tab app:

Select the icon on the Personal app card on the App features pane, and select Edit.

The details for Hello tab appear.
Select the icon for Hello tab, and select Edit to open the app details for updating.
Enter the app details for the Hello tab in Add a tab to your personal app.

Enter the following details:
- Name: Hello tab.
- Content URL and Website URL: the forwarding address in ngrok console session.
- Context: Select Personal tab.
Select Update.

The details of the Hello tab appear on the Personal app pane.
Select Save.

The Personal app pane now shows the new tab and an About tab created automatically.

Configure bot

It's easy to add the bots functionality to your app. The Hello World sample app already has a bot as its part, but you must register it with Teams.

Image showing bot app imported with no app ID

The bot that was imported from the sample doesn't have an associated app ID. You'll need to delete it, and create a new bot. Developer Portal creates a new app ID, and registers it with Teams.

Adding and configuring a bot involves:

Adding a new bot
Adding bot to app
Configuring bot scope

To add a new bot

Select the icon on the Bot card on the App features pane, and select Delete.
Select Tools to add capability.
Select Bot management on the Tools pane.
Select + New Bot on the Bot management pane.
Enter a suitable name for your bot, and select Add.

The Configure pane appears showing details of the new bot in the left pane.
Enter the forwarding URL from the ngrok console, and select Save.
Select Client secrets, and then select Add a client secret to your bot to generate a password for the bot.

Developer Portal generates a password for the bot.

You can use the icon to copy the password. For this tutorial, you don't need to copy it.
Select OK.
Select < Bots to return to Bot management pane.

The Bot management pane shows the new Bot added with an app ID.
Ensure that you save the Bot ID along with the password from the Client secret section.

To add bot to app

Open the App features pane, and select the Bot card.

The Bot pane appears.
Select your bot app from Select an existing bot.

The new bot is added to your app with its own app ID.

To configure bot scope

Select the icon on the new Bot card, and select Edit.
Move through the Bot pane to view the Commands section, and select + Add a Command.
Enter a suitable name and description for the Command.
Select all the three scopes for the command, and select Add.
- Personal
- Team
- Group Chat
The new command is added to the Commands section of the Bot pane.
Select Save.

The command details are saved.
Open App features pane, and select Personal app card to view your app's tab details.

You'll see that a tab for your new chat bot is added to your app.

Configure message extension

Message 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. Message extensions appear at the bottom of the compose box.

To add a new message extension:

Select the icon on the Message Extension card on the App features pane, and select Delete.
Select Message Extension from the App features pane.
Select the name of your bot app from the Select an existing bot dropdown list on the Message extension pane.
Select Save.

The message extension is saved, and the Commands section appears on the Message extension pane.
Select + Add a command to define the scope of what your message extension app can do.
Ensure that Search is selected as the type of command you want to add in the Add a command dialog.
Enter suitable information the following details:
- Command ID
- Command title
- Command description
Move through the dialog to view the remaining details.
Ensure Make default is selected.
Select the following contexts for the message extension command:
- Command box
- Compose box
- Message
Enter suitable information for the following details:
- Parameter name
- Parameter title
- Parameter description
Select Text as the type of input.
Select Save.
The message extension command is saved, and shows on the list of commands in the Message extension pane.
Select Save.
Open App features pane.

You'll see all three capabilities - personal tab app, bot, and message extension - configured for the Hello World app. The next step is to register your app in Teams and test your app.