Home » Blog » Microsoft Teams App development with ngrok

Microsoft Teams App development with ngrok

How to install Teams Manager for Microsoft Teams

Requirements for the development

The most important first

The entire code can be found on GitHub: https://github.com/Solutions2Share/SampleTeamsTabApp.

You can download or clone the sample, or you could follow the instructions and create a new Sample Teams Tab App.

MS Teams App Studio

Install the MS Teams App Studio via the following Link: https://aka.ms/InstallTeamsAppStudio

You need to log in with the account you want to develop with and install it into your tenant. You can find the complete Microsoft documentation under https://docs.microsoft.com/en-us/microsoftteams/platform/get-started/get-started-app-studio

Create a Sample MVC Project

Go to Visual Studio and create a new MVC Application:

Create a new MVC Application
Add folders and core references for MVC

As we want to create a MS Teams Tab Application you need to add a Controller and the following Views for our sample:

MSTeamsController.cs

Microsoft Teams Controller

_LayoutMSTeams.cshtml:

Layout Microsoft Teams

Configuration.cshtml:

Configuration

Index.cshtml:

Index

TeamsAppConfigureTab.js:

Microsoft Teams App configure tab

In line 46 we define the URL for the tab that will be created. Here you can fill some parameters so MS Teams will automatically detect them and fills them with the correct values. You could use for example:

  • {entityId}: The ID you supplied for the item in this tab when first configuring the tab.
  • {subEntityId}: The ID you supplied when generating a deep link for a specific item within this tab. This should be used to restore to a specific state within an entity; for example, scrolling to or activating a specific piece of content.
  • {loginHint}: A value suitable as a login hint for Azure AD. This is usually the login name of the current user, in their home tenant.
  • {userPrincipalName}: The User Principal Name of the current user, in the current tenant.
  • {userObjectId}: The Azure AD object ID of the current user, in the current tenant.
  • {theme}: The current UI theme such as default, dark, or contrast.
  • {groupId}: The ID of the Office 365 Group in which the tab resides.
  • {tid}: The Azure AD tenant ID of the current user.
  • {locale}: The current locale of the user formatted as languageId-countryId (for example, en-us).

More information in the documentation under https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/tabs/tabs-context

TeamsAppContextIntializer.js:

Microsoft Teams App context initializer

Test your application with F5 and remember your portnumber. You should see the following screen:

ASP.NET screen

Ngrok configuration

What is ngrok?

Ngrok is a tool which provides a public URL to your local hosted solutions. It creates a tunnel service to your localhost and functions as a DNS tool.

What is it useful for?

Ngrok is used whenever a public endpoint is needed for your local hosted application. For example, it can be used as a webhook URL. You can also use it for Microsoft Teams Bots and Microsoft Teams Apps.

Ngrok is not suitable for SharePoint Provider hosted Apps.

What are the advantages?

It is much faster than deploy it to e.g. an Azure-website.

  • Fast Debugging possible, since it is hosted locally and not on azure (Remote Debugging is very slow)
  • You don’t have to deploy changes to Azure every time
  • Reduced Azure costs

Installation

Visit ngrok.com. Register yourself and download the file:

Download and setup ngrok

Add ngrok to the Path Variables.

Add ngrok to the Path Variables
Edit environment variable

Run cmd and test it with “ngrok”:

cmd ngrok

Connect ngrok to your account by running a cmd with the following content:

ngrok authtoken <YOUR_AUTH_TOKEN>

ngrok authtoken

After connecting, do a restart!

Start Visual Studio

Find out the port by starting your app (e.g.: MVC Website) with F5:

Microsoft Teams Graph

Run the following command in a cmd window where ‘55065’ is the port which your application is running with:

ngrok http 55065–host-header=localhost

ngrok localhost

NOTE: You don’t need to host your application with HTTPS locally. Ngrok will automatically redirect it to the http localhost.

After starting your application and going into the forwarding URL (in our example: https://6ec8f719.ngrok.io) you will see your app loading. If you want a static subdomain every time you start the application, you will have to use the paid version of ngrok.

Otherwise, each time you run the command, you will get a random subdomain assigned to it.

In this example, we used the free version of ngrok.

If you want to inspect HTTP Traffic or analyze problems with ngrok visit the url: http://127.0.0.1:4040/ and click on ‘Inspect’.

ngrok inspect

Click ‘Status’ to see if everything works and to check how many connections are available.

Configuration and Metrics

Problems

If a ‘Tunnel xxxxx.ngrok.io not found’ error occurs, please try to host your application again (stop and press F5).

ngrok not found

Conclusion

The tool is very practical for team bots and could also be for team apps for tabs.

However, it must be said that the tool will only be helpful if you buy the Pro version (5€/month/user) where static SubDomains are available as an important feature.

If you have combined ngrok and your sample application successfully you should see the following screen:

ngrok application successfully

Create the MS Teams App

Go to the App Studio in your MS Teams App (teams.microsoft.com)

Create a new app in the Manifest editor

Microsoft Teams Manifest editor

Fill in all the required data for the App details:

Microsoft Teams App details

Go to Capabilities -> Tabs and select Add a Teams tab.

Add a Teams tab in Microsoft Teams

The configuration URL should now set to the ngrok URL added with “/MSTeams/configuration”. In my case: https://0f442812.ngrok.io/MSTeams/configuration:

Microsoft Teams Team tab

Here you could define some parameters that would be filled from MS Teams when calling the URL. For Example, you can use the following Parameters:

  • {entityId}: The ID you supplied for the item in this tab when first configuring the tab.
  • {subEntityId}: The ID you specified when creating a deep link for a specific element within this tab. Use this to restore a particular state within an entity, e.g. to scroll to or activate a particular asset.
  • {loginHint}: A value appropriate as a login hint for Azure AD. Typically, this is the login name of the current user in their home tenant.
  • {userPrincipalName}: The User Principal Name of the current user, in the current tenant.
  • {userObjectId}: The Azure AD object ID of the current user, in the current tenant.
  • {theme}: The current UI theme such as default, dark, or contrast.
  • {groupId}: The ID of the Office 365 Group in which the tab resides.
  • {tid}: The Azure AD tenant ID of the current user.
  • {locale}: The current locale of the user formatted as languageId-countryId (for example, en-us).

In the section Valid Domains, you can see your ngrok domain. Please do not add this domain explicitly again. This will get you to an error while adding your tab.

mvc Valid domains

Go to Test & Distribute and click on Install to install your app into an available team.

mvc Test and Distribute

Select Team and click on Install:

MVC Install Team

Select a channel and click on Set up the Tab:

Select a channel and set it up

If the Modal Dialog is closed and you are redirected to you Team, then something went wrong. You have to make sure that your browser Cache is empty and the URL for your Tab Configuration is working.

If you are seeing the following dialog everything is working correctly and you can finish it with saving the tab:

Save Teams tab

Then you are finished and should see the following tab with the Contextual Data:

Microsoft Teams Contextual Data

Congratulations! You have created your first MS Teams Tab app!

Get control over your Teams with Teams Manager

Leave a Reply

Your email address will not be published. Required fields are marked *

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.