Build and run your first Microsoft Teams app with Blazor

In this tutorial, you will learn how to create a new Microsoft Teams app in .NET/Blazor that implements a simple personal app to pull information from the Microsoft Graph. For example, a personal app includes a set of tabs for individual use. During the tutorial, you will learn about the structure of a Teams app, how to run an app locally, and how to deploy the app to Azure.

The app that is built displays basic user information for the current user. When permission is granted, the app will connect to the Microsoft Graph as the current user to get the complete profile.

Before you begin

Make sure your development environment is set up by installing the prerequisites.

Create your project

Use the Teams Toolkit to create your first project:

  1. Open Visual Studio 2019.

  2. Select Create a new project.

  3. Select Microsoft Teams App, then select Next. To help you find the template, use the project type Microsoft Teams.

  4. Enter a name and select Next.

  5. Enter the application name and company name.

  6. Select Create. The application name and company name are displayed to your end users. Your Teams app will be created within a few seconds. After the project is created, set up single sign-on with M365:

    1. Select Project > TeamsFx > Configure for SSO....
    2. When prompted, sign in to your M365 administrator account.

Take a tour of the source code

If you wish to skip this section for now, you can run your app locally.

After the Teams Toolkit configures your project, you have the components to build a basic personal app for Teams. The project directories and files display in the Solution Explorer area of Visual Studio 2019.

Screenshot showing app project files for a personal app in Visual Studio 2019.

  • The app icons are stored as PNG files in color.png and outline.png.
  • The app manifest for publishing through the Developer Portal for Teams is stored in Properties/manifest.json.
  • A backend controller is provided in Controllers/BackendController.cs for assisting with authentication.

Since you created a tab app during setup, the Teams Toolkit scaffolds all the necessary code for a basic tab as a Blazor Server.

  • Pages/Tab.razor is the front-end application's entry point.
  • TeamsFx.cs and JS/src/index.js is used for initializing communications with the Teams host.

You can add backend functionality by adding additional ASP.NET Core controllers to your application.

Run your app locally

Teams Toolkit allows you to run your app locally. This consists of several parts that are necessary to provide the correct infrastructure that Teams expects:

  • An application is registered with Azure Active Directory. This application has permissions associated with the location that the app is loaded from and any backend resources it accesses.
  • A web API is hosted (via IIS Express) to assist with authentication tasks, acting as a proxy between the app and Azure Active Directory.
  • An app manifest is generated and exists in the Developer Portal for Teams. Teams uses the app manifest to tell connected clients where to load the app from.

After this is done, the app can be loaded within the Teams client. We use the Teams web client so that we can see the HTML, CSS, and JavaScript code within a standard web development environment.

To build and run your app locally:

  1. From Visual Studio Code, press the F5 key to run your application in debug mode.

  2. If requested, install the self-signed SSL certificate for local debugging.

    Screenshot showing how the prompt to install a SSL certificate to enable Teams to load your application from localhost.

  3. Teams will be loaded in a web browser, and you will be prompted to sign in. If prompted to open Microsoft Teams, select Cancel to remain within the browser. Sign in with your M365 account.

  4. When prompted to install the app onto Teams, select Add.

    Your app will now be displayed:

    Screenshot of the completed app

    You can perform the debugging activities as if this were any other web application like setting breakpoints. The app supports hot reloading. If you change any file within the project, the page will be reloaded.

Learn what happens when you run your app locally in the debugger.

When you press the F5 key, the Teams Toolkit:

  1. Registers your application with Azure Active Directory.
  2. Registers your application for "side loading" in Microsoft Teams.
  3. Starts your application backend running locally.
  4. Starts your application front-end hosted locally.
  5. Starts Microsoft Teams in a web browser with a command to instruct Teams to side load the application (the URL is registered inside the application manifest).
Learn how to troubleshoot common issues when running your app locally.

To successfully run your app in Teams, you must have a Microsoft 365 development account that allows app side loading. For more information on account opening, see Prerequisites.

Deploy your app to Azure

Deployment consists of two steps:

  1. Necessary cloud resources are created. This is also known as provisioning.
  2. Start coding and copy your app into the created cloud resources.


Support for Blazor apps is new in Teams Toolkit. Provisioning and deployment are done with a combination of Visual Studio 2019 and the Developer Portal for Teams.

Provision and deploy your app to Azure App Service

  1. In Solution Explorer, right-click the project node and select Publish. You can also use the Build > Publish menu item.

    Select the Publish operation on the project

  2. In the Publish window, select Azure and select Next.

    Select Azure as the publishing target

  3. Select Azure App Service (Windows) and select Next.

    Select Azure App Service as the publishing target

  4. Select + to create a new App Service instance.

    Create a new instance.

  5. In the Create App Service (Windows) dialog, the Name, Subscription name, Resource Group, and Hosting Plan entry fields are populated. If you have already got an App Service running, existing settings are selected. You can opt to create a new resource group and hosting plan. When ready, select Create.

    Select hosting plan and subscription

  6. In the Publish dialog, the newly created instance has been automatically selected. When ready, select Finish.

    Select the new instance.

  7. Select the Edit (pencil) icon next to Deployment Mode, and select Self-contained.

    Select self-contained deployment mode.

  8. Select Publish.

    Publish your app to app service

    Visual Studio deploys the app to your Azure App Service, and the web app loads in your browser. Add /tab to the end of the URL to see your page.

    The project properties Publish pane shows the site URL and other details. Make a note of the site URL.

Create an environment for your app

The Developer Portal for Teams manages where the tabs for your app are loaded from with an Environment.

To create an environment:

  1. Open the Developer Portal for Teams. Sign in with your M365 administrative account.

  2. From the sidebar, select Apps.

  3. If you only have one app, it will be automatically selected. If not, select your app from the list.

  4. Select Environments.

    Select environments

  5. Select Create your first environment.

  6. Enter a name for your environment and select Add. For example, _Production_.

  7. Select Create your first environment variable.

  8. Enter azure_app_url for the Name. Enter your Azure site URL without the https:// as the Value.

    Create environment variable

    Press Add.

Update the app manifest

The app manifest loads the tab from a localhost URL. In this section, you will configure the app manifest to load the tab from the URL listed within the environment you just created.

  1. From the sidebar, select Basic information.

    Select basic information

  2. There are several places within the manifest that list a localhost:XXXXX as part of a URL. Replace all occurrences with {{azure_app_url}}, including the curly braces.

    Adjust basic information for the environment

  3. When complete, select Save.

  4. From the sidebar, select Capabilities.

    Select capabilities

  5. Select Personal Tab.

  6. Next to the Personal Tab, select the triple dots, then select Edit.

    Edit personal tab settings

  7. Replace the URL with the environment variable within the Content Url and Website Url fields.

    Edit personal tab URLs

  8. Select Update.

  9. Select Save.

  10. From the sidebar, select Single Sign-On.

  11. Replace the localhost within the Application ID URI with {{azure_app_url}}.

    Edit single sign-on Application ID URI

  12. Select Save.

  13. From the sidebar, select Domains.

  14. Select Add a domain.

  15. If {{azure_app_url}} is not listed as a valid domain, add it as a valid domain, then select Add.

    Add a domain

    You can now use the Preview in Teams option at the top of the page to launch your app within Teams.

See also