Create a Custom Personal Tab with ASP.NET Core MVC

In this quickstart we'll walk-through creating a custom personal tab with C# and ASP.Net Core MVC. We'll also use App Studio for Microsoft Teams to finalize your app manifest and deploy your tab to Teams.

Prerequisites

  • To complete this quickstart you'll need a Microsoft 365 tenant and a team configured with Allow uploading custom apps enabled. To learn more, see Prepare your Microsoft 365 tenant.

    • If you don't currently have a Microsoft 365 account, you can sign up for a free subscription through the Microsoft Developer Program. The subscription will remain active as long as you're using it for ongoing development.
  • You'll use App Studio to import your application to Teams. To install App Studio select Apps Store App at the bottom-left corner of the Teams app, and search for App Studio. Once you find the tile, select it and choose install in the pop-up window dialog box.

In addition, this project requires that you have the following installed in your development environment:

  • The current version the Visual Studio IDE with the .NET CORE cross-platform development workload installed. If you don't already have Visual Studio, you can download and install the latest Microsoft Visual Studio Community version for free.

  • The ngrok reverse proxy tool. You'll use ngrok to create a tunnel to your locally running web server's publicly-available HTTPS endpoints. You can download it here.

Get the source code

Open a command prompt and create a new directory for your tab project. We have provided a simple project to get you started. To retrieve the source code you can download the zip folder and extract the files or clone the sample repository into your new directory:

git clone https://github.com/OfficeDev/microsoft-teams-sample-tabs.git

Once you have the source code, open Visual Studio and select Open a project or solution. Navigate to the tab application directory and open PersonalTabMVC.sln.

To build and run your application press F5 or choose Start Debugging from the Debug menu. In a browser navigate to the URLs below to verify that the application loaded properly:

  • http://localhost:44335
  • http://localhost:44335/privacy
  • http://localhost:44335/tou

Review the source code

Startup.cs

This project was created from an ASP. NET Core 2.2 Web Application empty template with the Advanced - Configure for HTTPS check box selected at setup. The MVC services are registered by the dependency injection framework's ConfigureServices() method. Additionally, the empty template doesn't enable serving static content by default, so the static files middleware is added to the Configure() method:

public void ConfigureServices(IServiceCollection services)
  {
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
  }
public void Configure(IApplicationBuilder app)
  {
    app.UseStaticFiles();
    app.UseMvc();
  }

wwwroot folder

In ASP. NET Core, the web root folder is where the application looks for static files.

AppManifest folder

This folder contains the following required app package files:

  • A full color icon measuring 192 x 192 pixels.
  • A transparent outline icon measuring 32 x 32 pixels.
  • A manifest.json file that specifies the attributes of your app.

These files need to be zipped in an app package for use in uploading your tab to Teams. Microsoft Teams will load the contentUrl specified in your manifest, embed it in an IFrame, and render it in your tab.

.csproj

In the Visual Studio Solution Explorer window right-click on the project and select Edit Project File. At the bottom of the file you'll see the code that creates and updates your zip folder when the application builds:

<PropertyGroup>
    <PostBuildEvent>powershell.exe Compress-Archive -Path \"$(ProjectDir)AppManifest\*\" -DestinationPath \"$(TargetDir)tab.zip\" -Force</PostBuildEvent>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="AppManifest\icon-outline.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\icon-color.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\manifest.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
  </ItemGroup>

Models

PersonalTab.cs presents a Message object and methods that will be called from PersonalTabController when a user selects a button in the PersonalTab View.

Views

Home

ASP. NET Core treats files called Index as the default or home page for the site. When your browser URL points to the root of the site, Index.cshtml will be displayed as the home page for your application.

Shared

The partial view markup _Layout.cshtml contains the application's overall page structure and shared visual elements. It will also reference the Teams Library.

Controllers

The controllers use the ViewBag property to transfer values dynamically to the Views.

Update your application

_Layout.cshtml

For your tab to display in Teams, you must include the Microsoft Teams JavaScript client SDK and include a call to microsoftTeams.initialize() after your page loads. This is how your tab and the Teams app communicate:

  • Navigate to the Shared folder, open _Layout.cshtml, and add the following to the <head> tags section:

    `<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.min.js"></script>`
    `<script src="https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js"></script>`
    

PersonalTab.cshtml

Open PersonalTab.cshtml and update the embedded <script> tags by calling microsoftTeams.initialize().

Make sure to save your updated PersonalTab.cshtml.

Establish a secure tunnel to your tab

Microsoft Teams is an entirely cloud-based product and requires that your tab content be available from the cloud using HTTPS endpoints. Teams doesn't allow local hosting. You'll need to either publish your tab to a public URL, or use a proxy that will expose your local port to an internet-facing URL.

To test your tab you'll use ngrok. Your server's web endpoints will be available while ngrok is running on your local machine. If you close ngrok, the URLs will be different the next time you start it.

  • Open a command prompt in the root of your project directory and run the following command:

    ngrok http https://localhost:44345 -host-header="localhost:44345"
    
  • Ngrok will listen to requests from the internet and will route them to your application when it is running on port 44325. It should resemble https://y8rPrT2b.ngrok.io/ where y8rPrT2b is replaced by your ngrok alpha-numeric HTTPS URL.

  • Be sure to keep the command prompt with ngrok running, and to make a note of the URL — you'll need it later.

  • Verify that ngrok is running and working properly by opening your browser and going to your content page via the ngrok HTTPS URL that was provided in your command prompt window.

Tip

You need to have both your application in Visual Studio and ngrok running to complete this quickstart. If you need to stop running your application in Visual Studio to work on it, keep ngrok running. It will continue to listen and will resume routing your application's request when it restarts in Visual Studio. If you have to restart the ngrok service it will return a new URL and you'll have to update every place that uses that URL.

Run your application

  • In Visual Studio press F5 or choose Start Debugging from your application's Debug menu.

Upload your tab to Teams with App Studio

Note

We use App Studio to edit your manifest.json file and upload the completed package to Teams. You can also manually edit manifest.json if you prefer. If you do, be sure to build the solution again to create the Tab.zip file to upload.

  • Open the Microsoft Teams client. If you use the web based version you can inspect your front-end code using your browser's developer tools.

  • Open App studio and select the Manifest editor tab.

  • Select the Import an existing app tile in the Manifest editor to begin updating the app package for your tab. The source code comes with its own partially complete manifest. The name of your app package is tab.zip. It should be found here:

    /bin/Debug/netcoreapp2.2/Tab.zip
    
  • Upload Tab.zip to App Studio.

Update your app package with Manifest editor

Once you've uploaded your app package into App Studio, you'll need to finish configuring it.

  • Select the tile for your newly imported tab in the right panel of the Manifest editor welcome page.

There's a list of steps in the left-hand side of the Manifest editor, and on the right, a list of properties that need to have values for each of those steps. Much of the information has been provided by your manifest.json but there are a few fields that you'll need to update:

Details: App details

In the App details section:

  • Under Identification select Generate to generate a new App Id for your app.

  • Under Developer information update the Website URL with your ngrok HTTPS URL.

  • Under App URLs update the Privacy statement to https://<yourngrokurl>/privacy and Terms of use to https://<yourngrokurl>/tou>.

Capabilities: Tabs

In the Tabs section:

  • Under Add a personal tab select Add. You will be presented with a pop-up dialogue window.

  • Complete the Name field.

  • Complete the Entity Id field.

  • Update the Content URL field with to https://<yourngrokurl>/personalTab.

  • Leave the Website URL field blank.

  • Select Save.

Finish: Domains and permissions

In the Domains and permissions section, the Domains from your tabs field should contain your ngrok URL without the HTTPS prefix - <yourngrokurl>.ngrok.io/.

Finish: Test and distribute

Important

In the Description field on the right you'll see the following warning:

⚠ "The 'validDomains' array cannot contain a tunneling site..."

This warning can be ignored while testing your tab.

In the Test and distribute section:

  • Select Install.

  • In the pop-up window make sure that Add for you is set to Yes and Add to a team or chat is set to No.

  • Select Install.

  • In the next pop-up window select Open and your tab will be displayed.

View your personal tab

  • In the navigation bar located at the far-left of the Teams App, select the ... menu. You'll be presented with a list of personal apps.

  • Select your tab from the list to view.

Next step