Choose a setup to test and debug your Microsoft Teams app
Microsoft Teams apps contain one or more capabilities and the ways to run or even host them are different. For debugging, use one of the following ways:
- Purely local: For bots, you can test your experience in the Bot Emulator. For other content, you can run locally in your browser and address content through
- Locally hosted in Teams: This involves running the app locally in tunneling software and creating a package to upload into Teams. This permits you to easily run and debug your app within the Teams client.
- Cloud-hosted in Teams: This truly simulates the production level support for a Teams app. It involves uploading your solution to your externally accessible server or cloud provider of choice and creating a package to upload into Teams.
Run the experience from your own computer for purely local or local Teams testing. By doing this, you can compile and run within your integrated development environment and take full advantage of techniques, such as breakpoints and step debugging.
For production-scale debugging and testing, we recommend that you follow your own company guidelines to ensure you are able to support testing, staging, and deployment through your own processes.
Use multiple manifests and packages to maintain separation between production and development services. For example, you might choose to register separate development and production bots and create appropriate packages to upload them in your testing environment. We also recommend, you upload and test your production package before submitting your app for publishing in our app store or distributing to customers.
Running the bot locally does not give you access to Teams app functionality or Teams-specific bot functions like roster calls and other channel-specific functionality. In addition, some capabilities are permitted by the Bot Framework in the Bot Emulator that might not function when running in Microsoft Teams.
Your bot can run within the Bot Emulator. This enables you to test some of the core logic of the bot, see a rough layout of messages, and perform simple tests. Following are the steps:
- Run the code locally.
- Launch the Bot Emulator and set the URL:
- Leave the Microsoft app ID and Microsoft app password blank, to match the default environment variables.
Microsoft Teams is an entirely cloud-based product, it requires all services it accesses to be available publicly using HTTPS endpoints. Therefore, to enable your app to work within Teams, you need to either publish the code to the cloud of your choice or make our local running instance externally accessible. We can do the latter with tunneling software.
Although you can use any tool of your choice, we use and recommend ngrok, which creates an externally addressable URL for a port you open locally on your machine.
To set up ngrok in preparation for running your Microsoft Teams app locally
- Go to the directory where you have ngrok.exe installed in a terminal application. You may want to add it as a path variable to avoid this step.
- Run, for example,
ngrok http 3978 --host-header=localhost:3978, or replace the port number as needed. This launches ngrok to list on the port you specify. In return, it gives you an externally addressable URL valid for as long as ngrok is running.
If you stop and restart ngrok, the URL changes.
To use ngrok in your project based on the capabilities you are using, you must replace all URL references in your code, configuration, and manifest.json file to use this URL endpoint.
For bots registered in the Microsoft Bot Framework, update the bot's messaging endpoint to use this new ngrok endpoint. For example,
https://2d1224fb.ngrok.io/api/messages. You can validate that ngrok is working by testing the bot response in the Bot Framework portal's Test chat window. Again, like the emulator, this test does not permit you to access Teams-specific functionality.
To update the messaging endpoint for a bot, you must use the Bot Framework. Select your bot in your list of bots in Bot Framework. You do not need to migrate your bot to Microsoft Azure. You can also update your messaging endpoint through App Studio.
You can use any externally addressable service to host your development and production code and their HTTPS endpoints. There is no expectation that your capabilities reside on the same service. We require all domains to be accessed from your Microsoft Teams apps listed in the
validDomains object in the
To ensure a secure environment, be explicit about the exact domain and subdomains you reference and those domains must be in your control. For example,
*.azurewebsites.net is not recommended, however
contoso.azurewebsites.net is recommended.
Load and run your experience
To load and run your experience within Microsoft Teams, you need to create a package and upload it into Teams. For more information, see: