Part 3: Creating your first Microsoft Teams app (this one)
Part 4: Configurable Tabs in Microsoft Teams
After setting up your development environment and getting
ramped up with ngrok we will start developing our first Teams app. The quickest
way to start is with App studio. App Studio is a Microsoft app from the Teams
store especially created for helping you with Teams development.
This will help you out when starting out with Teams
development. Configuring the manifest can be overwhelming so I really recommend
you check it out
Now let’s get started with our first Teams app. The quickest
way to get started it with tabs. There are 2 kind of tabs:
Static: This is for a 1:1 experience with a
user. So, an individual user will only see this tab.
Configurable: This is for usage in a channel or a
group of users.
The simplest app for Microsoft Teams you can build is a
static tab. Just add the following information to your manifest:
This will specify a unique id for
the tab, of course it needs a name. The content url is what is shown in the
Teams tab and the website url is what is shown when you want to see the full
content (so if you click on the link) So also need to define the scope but
since a static tab can only exist in a 1:1 scope it will always be the value of
Now for creating this simple app we don’t even need to code
or create a solution but in the interest of this blog post series we will start
out with a small solution that we build out to become one big Teams app.
Start up Visual Studio and create a new project. Remember
for Teams everything can also be done in Node.js and with Typescript. To get
started there I recommend the Microsoft Teams Yeoman generator which will do
the scaffolding for you https://github.com/OfficeDev/generator-teams
In this example we will start with the “Core” bot template.
In this a lot of boiler plate code is already setup. We won’t be using
everything but this way you can easily extend this example if you want to build
in some real functionality inside your bot.
Now since this is a .Net core app our default page resides
in the “wwwroot” folder. This is the one we are going to show inside our Teams
app. Let’s make sure that the template is working and let’s just start up the
This seems to be working.
Now to create the manifest. A small trick that I always do (because you will need to make a lot of changes on the manifest) is creating a separate folder for this in the solution. Add a new manifest.json file and 2 logo’s for your app.
Now there are a few ways you can automatically create the
zip package needed for Teams and this one is one of them.
Edit the project file
And add the following to the bottom of the file. Right above
the last xml </project> tag.
Now for the contents of the manifest file. More information
about Teams manifests can be found here
Now we need to specify our information in the static tabs section. Therefore we need to fill in the information in the corresponding section, but wait… it looks like MS Teams only accepts HTTPS endpoint in it’s manifest. This means that we need to start our project on an HTTPS endpoint. We can change this in the settings of the project.
Right-click on the project and open up the properties pane.
And under the “Debug” section we can specify to use SSL.
This will provide us with an HTTPS endpoint. First of all enter this information in the manifest static tab section under “ContentUrl” and “websiteUrl”. Since we are not yet differentiating between the page running under a Teams context or in a browser, we can use the same endpoint. If we were building an application which needed to behave differently in Teams than in a normal browsing session, then we could differentiate this here.
Now let’s test it out. Run the solution and sideload your
first Teams app to Teams.
The zip file can be found in the “Bin” folder of the solution
Click install and open.
And we have our first Teams app with a static tab working
This of course is just a demo. The main objective here is that you get your application as a static tab in Teams. This can be an existing app and then you would just need to add the specific Teams items.
One of the main reasons for writing this specific post which is not specific to Microsoft Teams development is the misconceptions there exist around ngrok. I’ve seen to many (especially Microsoft code examples) which specify that you cannot use a custom subdomain and that you are stuck with “https://SomeRandomThing.ngrok.io” unless you pay up. This is not true… It’s just if you want to claim the subdomain as you’re own… then you have to pay… but more in the blog post below.
Another way to do this is to use ngrok. ngrok is mostly known for developing webhooks. It will provide you with a public url. This url will then be tunneled to your local device effectively giving you an endpoint available in the cloud. It’s like putting your local machine’s on a public IP. Now to do this ngrok needs something that runs on your device to setup the tunnel. So download the tool from there website and you’re good to go… but not quite.
After you downloaded the zip file you will notice that there is only a single exe inside of it. Put it in a folder on your drive and open a command line. Now go to the folder and then start ngrok by typing the command ‘ngrok http 80 ‘ this means start ngrok and map port 80 on http. Cool thing is that when the tools start up it will create 3 url’s for you. 1 on an http endpoint, 1 on an https endpoint and a localhost webserver which you can use to inspect what is going over the wire. Let’s see this with an example:
Creating a new project
Firstly, we need to have some code running on localhost. So
open Visual Studio and create a new project.
Now we need a website so choose a web project. This can be
an asp.net core web app or an old fashioned asp.net web application. For this
example this doesn’t matter because we are not going to do much with it. I’m
with the cool kids now so I chose a core app.
Next choose a web application so that we get some basic
Now your default test web app is ready. If you now press
start (F5) then you will see a page popping up.
Take notice of the url of the web application. It’s now
running on my local machine. Which means that nobody (person or system) can
reach my web application. Now let’s go back to our command line. We now want
our web application to be publicly available. Since this is running on port
54336 we need to let ngrok now this. So the following command will do this:
“ngrok http 54336 –host-header localhost”
If we now go to the provided url we can also reach our web
The host-header part of the command is for Visual Studio.
When you are going to your web application it knows that it’s running on
localhost. This means that connecting to it with another url it will fail. This
will rewrite the host-header part of the request to let Visual Studio think
that it’s still being connected to from localhost.
If we now go to one of the 2 provided url’s, you will see
your web application also there. This means that a system running in the cloud
(like Teams) also can connect to it.
Now this is the basic’s of running ngrok. You can already
image that always doing this will get annoying after a while so next are some
tips and tricks
Create a configuration file
Ngrok can also work with a config file. This way you don’t
need to enter this long command all the time
First create an auth token. This can be done by creating an
account on there website. You can have a paid account if you want but it’s not
required. I just linked the account to my github which makes login so much
easier. Now after creating an account on the left in your dashboard you will
see your auth token. The command is also specified. Be aware that if you are
using Windows like myself that you must change the command a little bit. You
can remove the $ ./ Just enter “ngrok authtoken <authtoken>” in the
command line. This will save the auth token to a configuration file. In my case
it’s located under my user directory.
Now this configuration file can be used to specify all your
If you want the exact same thing as we did before your
configuration file should look like this.
Now be aware that this configuration file is a yaml file. So
the spaces and tabs really have a meaning. It’s like Python programming, if you
put something not in the correct indentation you can lose hours (like I did)
with searching for a reason why something is not working.
Now if you need the public url where you’re code is running
on…. like for instance in your manifest when you develop on Microsoft teams
it’s a pain to change this every morning or every time you start developing
again. So it would be nice if the url is always the same. This can be done with
the “subdomain” configuration. So an example of my configuration file for a
Teams app that I’m building looks more like:
This means that every time I fire up ngrok that different
app’s that can be running on different ports are mapped correctly to their
subdomain. This way I don’t need to update the manifest when starting in the
Now to start ngrok with all these different settings just
type ‘ngrok start –all’ (the all stands for all the different configuration
inside the config file. If you want you can also start a single one. That’s why
they all get a different name)
Inspection of what is going over the wire
You already noticed the 127.0.0.1 url. This is a small
webserver that comes with ngrok where you can inspect your requests. Think of
it as the small brother of Fiddler https://www.telerik.com/fiddler
If you browse to this url (ngrok must be running) then you
can check out the requests and their answers. This is helpful sometimes when
doing Teams development. Especially when creating bot’s because they are quite
chatty over the wire. This will even allow you to replay a request if needed.
In this ramp-up we will start from scratch with Microsoft Teams Development. Every week I will publish a post and in this blog series we will go through the different parts that are needed for Teams Development and the different possibilities with developing on the Teams platform. I will also make a video series of this with my fellow MVP Thomas Gölles
As always with these kind of blog posts things in Office 365 change and the information in here will be inaccurate. I will try to keep everything updated as it changes but if something is wrong or you have any questions don’t hesitate to contact me.
In this first part we will start at the beginning which always is… how to setup your development environment. Next posts go deeper into Microsoft Teams Development:
Part 1: Setting up your development environment
Part 2: ngrok: why and how to use it
Part 3: Creating your first Microsoft Teams app
First off in Teams development you can pick your poison. If you like C# development then you can develop onto Teams in C#. If you rather develop into Node.JS then that’s also possible. The scaffolding tools and development tools can change… but the result will remain the same. This is one of the strong points of Teams development. Be sure to check out https://docs.microsoft.com/en-us/microsoftteams/platform/ for more information
Now to get started with Microsoft Teams development you of course need an Office 365 tenant. If you don’t have one you can get one for free to do your development on. But be aware, you are getting this tenant for development purposes from Microsoft, don’t use it for real life stuff. Check out the Office 365 developer program for more information.
If you already have a tenant and you want to use that one
then you must have one of the following licenses:
Enterprise E1, E3, and E5
Education, Education Plus, and Education E5 (or as my friend Jethro Segers noticed it’s A1, A3 and A5 or Office 365 for Students/Teachers)
When you have a tenant to do your development on you will need to turn on Microsoft Teams. If this is still needed. This depends on when you created your tenant. If you took a fresh developer Tenant then this is not needed anymore.
Here under the “Apps” menu you can turn on sideloading of
And optionally you can turn on the developer preview of the
Teams client. This is not required but depending on what you are going to build
you might need it.
Now Microsoft Teams development requires 2 basic items:
A manifest and your code. The manifest is part of the
Microsoft Teams app that you upload to Teams. This tells Teams what you have
built, what’s it called, and all those things needed by Teams to run your app.
A manifest consists out of the following parts:
The top ones are required inside of the manifest. The bottom items not. But if you just fill out the top ones you will have an app that has no functionalities.
This also means that we need a second part and that’s of course a website to host your code. This is where the code you have written will be hosted. If you develop something for Microsoft Teams it will always will need to be hosted somewhere else. It could be that this is in Azure. But it also could be inside SharePoint (with an SPFx app) or even on AWS.
Of course, you will need something to write your code in. This is something that you must choose yourself. Do you prefer Visual Studio Code or Visual Studio? Doesn’t matter anymore these days.
After these steps your developer environment should be ready… but a crucial helping tool is still missing. That would be ngrok. In the next post we will go deeper why we need this tool and how to set it up.
When quickly creating a bot channels registration in Azure (I usually do this for testing something) You can select to create your own Microsoft App ID and Secret. If you do this then you can copy/paste them because you need them later on. But when you select “Auto create App ID and Secret” they don’t show you the secret in your bot settings.
You can see the App ID but not the App Secret
If you want to find your App secret just look inside you notifications. Click on the name of the item you just created and you will get all the information used for creating it (also very handy if you ever want to create an ARM template or use the CLI). There you can find your secret under the “Inputs” section.
Under the inputs section you can see your App ID and App Secret
When developing a Microsoft Teams solution in C# with Visual Studio, I often find myself changing the manifest file. Mainly because I use ngrok to tunnel from Teams to my local development machine. So every time I fire up a new instance of ngrok I need to change the manifest file to a new endpoint url. A quick trick to make this process faster is adding the needed files to my solution. This way I keep it all in one place.
A package that you need to upload to Teams is a file that is just a zip package containing 3 items. The manifest file that describes information about you and your app. And 2 icons that are used in Teams to visualise your app. More information can be found here
Automatically generate a package after every build
Now to create the manifest file automatically after every build I simply add a package.json file and a gulpfile.js to the solution. This way I can use the build in task runner from VS. This will automatically create a new version of the package file every time I build my solution.
Add a new npm configuration file to the project
Add the below piece of code to the configuration file. This is so that you can use gulp and gulp-zip to create a zip file.
Now I you fire up the task runner explorer (under View – Other windows) you can see the task you just created. And if you right click on it you can select to have it run after every build.
My packageCreation task will run after every build
It will take the contents of my manifest folder and zip it into a package in the debug folder This way I’m my package I upload to Teams is always in sync with what’s in my solution
One last recommendation I can make is that when starting out with creating manifests and packages for Teams. There are several options to do this. There is the Teams Yeoman generator or you can use the App Studio that is available as app in Microsoft Teams.