14.1.Introduction

Microsoft announced Teams in November 2016 and launched the service worldwide on 14 March 2017. Since then, the development of the application has been stormy, adding new functionality almost every week. At the beginning, Teams was no more than the combination of some functionality of Exchange (Groups) and SharePoint (Libraries) in one user interface, and certain experimental extensibility options. But because Microsoft sees Teams as a key component in its strategy for Office 365, the development of new functionality and interoperability has been very fast. In May 2017, Microsoft announced Microsoft Teams was replacing Microsoft Classroom in Office 365 Education; in September 2017, it was made known that it will replace Skype for Business, and in 2018, that StaffHub will be retired and its functionality moved to Teams.

While Teams was engulfing other products, its ability to interact with the external world was also improving. Initially, it was only possible to add bots and a couple of connectors with external applications, but now, it is interoperable with hundreds of applications, and developers can create new connectors, message extensions, Webhooks, and SharePoint Framework components. Also, the support for Microsoft Graph (using REST services) is getting better and, in April 2019, the general availability of the Microsoft Teams PowerShell module was announced.

There are several ways to extend the functionality of Teams:

-Tabs that provide a full-screen web experience, embedded in the main presentation zone of the Teams user interface.

-Bots that interact with members of a conversation through chat and can respond to events.

-Webhooks and Connectors that enable external services to send and receive messages.

-Messaging extensions that allow users to interact with Web services through buttons and forms from the Teams client user interface.

-SharePoint Framework (SPFx) components that are created as SharePoint Client WebParts.

Teams is not a hosting service: The customizations added to Teams are always hosted externally. The package to add the functionality to Teams contains a manifest with metadata about the app (name, icons, etc.), and pointers to the web services of the app. Also, take into consideration that any functionality exposed in a Microsoft Teams app is publicly available over the internet. If the app provides access to confidential or protected information, the app self should take care of authentication and authorization.

14.2.Teams configuration for developing

Teams can be activated for all users from the Central Administration of Office 365. Also, the access can be configured by the user if necessary.

For developing, sideloading (installation of applications without using Microsoft's application-distribution method) must be activated at three levels before it can be used:

-From the Teams Admin Center, open the Terms apps section, click on Setup policies, and open the Global (Org-wide default) policy. Flip the Upload custom apps button to On and save the configuration.

-From the Teams Admin Center, open the Terms apps section and use the Org-wide app settings button. Move the Custom apps selector to On.

-Each Team has the option Allow members to upload custom apps in the Manage Team - Settings - Member permissions window that should be activated.

14.3.Developing for Teams and development tools

A customization for Teams consists of a web application of a series of JavaScript files that must be hosted outside Teams, and a manifest that ensures the liaison between the external application and Teams. In fact, any web application could, in theory, be connected to Teams.

The main development tool to create new functionality for Teams is Visual Studio, even though Visual Studio Code can eventually be used as well. Microsoft has made some tools available to facilitate the development of customizations for Teams. Additionally, other third-party tools can help, especially for debugging.

14.3.1.Location of the Teams objects

The components available in the Teams client are physically located in SharePoint, Exchange, and Skype:

Chat is formally linked to the Skype server. Skype is being replaced by Teams, and its complete functionality will be available in Teams.

Teams is physically one Site Collections in SharePoint, plus one Group in Exchange. They can be reached programmatically using the APIs for Teams, SharePoint, and Exchange.

Each Team has different components:

-Channels. There are two types of Channels:

oStandard (Public) Channels that use the base SharePoint Site Collection and Exchange Group created for the Team.

oPrivate Channels that use the same Exchange Group as the Team, and a separated SharePoint Site Collection. This Site Collection is not visible from the SharePoint Central Administration page, but it can be reached programmatically as any other SharePoint Site Collection.

Each Channel is formed of three default components:

-Conversations, that are saved in the Exchange Group. The Group API doesn't allow access to the Conversations.

-Files, that are saved in the Documents Library of the SharePoint root site in the Site Collection. Each Channel has one folder in the Library to save its files. Full programming access granted using the SharePoint APIs.

-Wikies, saved as .mht files (one for each Wiki) in the Teams Wiki Data Library of SharePoint. The .mht files are MIME HTML formatted files which save HTML, images and other linked resources into a single file. The SharePoint APIs allow access to these files.

Calendar in Teams is the calendar of the user, saved in Exchange. It is reachable programmatically using the Exchange APIs.

14.3.2.Teams App Studio

The Teams App Studio is a tool to help you build apps for Teams. It facilitates to start developing or integrating own service, streamlines the creation of the manifest for the apps, and provides other tools like a Card Editor and a React control library.

Teams App Studio is also an app which can be found in the Teams store. Click on the Apps button in the Teams client and search for App Studio in the store. After installing the app, it will be reachable from the ellipse button (...) on the left side menu of the user interface.

14.3.3.Teams Developer Preview

The Teams Developer Preview is a Microsoft public program for developers that provides early access to unreleased features in Teams. This allows to explore and test upcoming features for potential inclusion in Microsoft Teams. They are provided for testing and exploration purposes only. They should not be used in production applications.

The Developer Preview can be enabled per Teams Client; thus, it doesn't affect the entire organization, only the instance (Teams Desktop or Teams Web application) where it is activated.

To activate the Developer Preview on a computer or web client, the uploading of apps must be activated as described at the beginning of the section. Click on the profile button (upper right corner of the Teams interface, the button with the picture of the user) to display the Teams menu, and then select About and click on Developer preview to turn it on or off.

The manifest used for customized components must have the property manifestVersion with the value devPreview. The functionality available changes very often and sometimes it is not documented by Microsoft.

14.3.4.ngrok

To load custom Team apps, the app must be available from the internet; it cannot be used running from a local IIS. There are two possibilities to make the Teams app in development reachable from the internet: Hosting the app in a public server, such as Microsoft Azure, or creating a tunnel to the local process on the development machine using ngrok, an application (available for Windows, Linux and Mac) that creates public URLs for testing of software that runs in a local development computer.

ngrok is a free tool that can be downloaded from https://ngrok.com/download. Unzip ngrok to a directory in the development computer. Run the Teams app under development from Visual Studio: The app will be available locally from a URL like http://localhost:3333. Open a PowerShell console, relocate the pointer to the folder where ngrok is unzipped, and run it using the syntax:

Ensure that you use the same port for the http parameter and the localhost parameter. The console will respond indicating the external URL generated from ngrok in the form of http(s)://[identifier].ngrok.io. For the free version of ngrok, a session can expand for max 8 hours (it is not necessary to register in the ngrok site to use the free version). From this moment, the application available locally under the URL http://localhost:3333 will be also available from the public internet URL http(s)://[identifier].ngrok.io. To stop the tunnel, use the command Ctrl-c.

ngrok provides a real-time web user interface as well, to gather all the HTTP traffic running over the tunnel. After starting ngrok, open the URL given under Web Interface in the PowerShell window (for example, http://127.0.0.1:4040) in a web browser to review all the traffic details.

14.3.5.Cards

Cards are an open format that enables developers to exchange content for user interfaces in a commonly and consistently way. Cards are used in messages, bots, emails, and any kind of application that needs to show information for users. There are eight types of Cards available for Teams: Adaptive, Hero, List, Office 365 Connector, Receipt, Signin, Thumbnail, and Collections. No type can be used for any other type of application: Teams Connectors, for example, only accept Cards of the Office 365 Connector type.

Cards are described as JSON objects with a defined syntax. Microsoft provides extensive information about Adaptive Cards in its site https://docs.microsoft.com/en-us/adaptive-cards/.

For Message and Adaptive Cards, the Microsoft site https://messagecardplayground.azurewebsites.net offers several examples showing the JSON code and the Card result. This site is becoming replaced by the Microsoft site https://amdesigner.azurewebsites.net, that also has several examples and a Card generator but only for Adaptive Cards.

14.4.Teams Tabs

Tabs are Web pages embedded in Microsoft Teams. There are two types of Tabs available in Teams:

-Personal Tabs are scoped to a single user. They are pinned to the left navigation bar, under the ellipse (...) button.

-Channel/Group Tabs deliver content to channels and group chats. They are pinned to the top-horizontal bar (Tabs bar).

The Web pages to be used for Tabs must be hosted as HTTPS (secure socket layers) and able to be embedded in an iFrame by the Teams client.

14.4.1.Personal Tabs

Fundamentally, Tabs with a personal scope consist of Web pages that are framed within the Teams client, and that are accessible after installation from the ellipse menu at the left side of the Teams interface.

Any public Web page can be set as Personal Tab. For the next example, Visual Studio is used to create a .NET Framework ASP.NET Web Forms application, but an MVC application using .NET Framework or .NET Core would suffice as well.

Start Visual Studio and create a new solution of the type ASP.NET Web Application (.Net Framework). Select Empty as the type project, select Web Forms in the Core references menu, and deselect Configure for HTTPS.

Add a new Web Form called GenerateGuid.aspx to the solution. This will be the page with the functionality for the Tab. There are one button and two labels in the aspx page, one for the new GUID and other to show information from the context. The styles from the .css file are used for styling.

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="GenerateGuid.aspx.cs" 
    Inherits="KKJA.GenerateGuid" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <script src="https://statics.teams.microsoft.com/sdk/v1.0/js/MicrosoftTeams.min.js" 
        type="text/javascript"></script>
    <script src="GenerateAppScripts.js" type="text/javascript"></script>
    <link rel="stylesheet" href="GenerateThemes.css" type="text/css" /> 
</head>
<body class="theme-light">
    <form id="form1" runat="server">
        <div class="surface font-semibold font-title"><h2>Generate a new GUID</h2></div>
        <div>
            <p>
                <asp:Button ID="btnGenerateGuid" runat="server" Text="Generate" 
                    OnClick="btnGenerateGuid_Click" />
            </p>
            <p class="surface">
                <asp:Label ID="lblNewGuid" runat="server" Text=""></asp:Label><br />
                <asp:Label ID="lblContextInfo" runat="server" Text=""></asp:Label>
            </p>
        </div>
    </form>
</body>
</html>

The .aspx page has a reference to the MicrosoftTeams.min.js file from the team's Content Distribution Network (CDN). This file belongs to the Team's JavaScript client SDK, a part of the Microsoft Teams developer platform, and it contains methods to facilitate the integration of custom services with Teams. There is also a reference to the custom stylesheet file GenerateThemes.css that contains all the styling classes for the Teams themes, and a reference to the GenerateAppScripts.js containing the JavaScript routine that initializes the Team's client SDK, checks the initial theme chosen by the user and maintains it applied, defines the event handler for the change of themes, and sets a theme when the change of theme event is detected. The context contains some information about Teams, the user and the session; the label lblContextInfo shows, for example, the value of the loginHint property present in the context.

(function () {
    'use strict';

    microsoftTeams.initialize();

    microsoftTeams.getContext(function (context) {
        if (context && context.theme) {
            document.getElementById('lblContextInfo').innerText = context.loginHint;
            setTheme(context.theme);
        }
    });

    microsoftTeams.registerOnThemeChangeHandler(function (theme) {
        setTheme(theme);
    });

    function setTheme(theme) {
        if (theme) {
        // Possible values for theme: 'default', 'light', 'dark' and 'contrast'
        document.body.className = 'theme-' + (theme === 'default' ? 'light' : theme);
        }
    }
})();

The code-behind file for the .aspx page generates a GUID when the button is used and shows its value in the label.

        protected void btnGenerateGuid_Click(object sender, EventArgs e)
        {
            lblNewGuid.Text = Guid.NewGuid().ToString();
        }

Two other aspx pages are necessary: One to show the privacy statement, and another for the terms of use. In this example, there is only some text in the pages, but any kind of functionality can be used.

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Privacy.aspx.cs" 
    Inherits="KKJA.Privacy" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <script src="https://statics.teams.microsoft.com/sdk/v1.0/js/MicrosoftTeams.min.js" 
        type="text/javascript"></script>
    <script src="GenerateAppScripts.js" type="text/javascript"></script>
    <link rel="stylesheet" href="GenerateThemes.css" type="text/css" /> 
</head>
<body class="theme-light">
    <form id="form1" runat="server">
        <div>
            This is the Privacy Statement page
        </div>
    </form>
</body>
</html>

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Terms.aspx.cs" Inherits="KKJA.Terms" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <script src="https://statics.teams.microsoft.com/sdk/v1.0/js/MicrosoftTeams.min.js" 
        type="text/javascript"></script>
    <script src="GenerateAppScripts.js" type="text/javascript"></script>
    <link rel="stylesheet" href="GenerateThemes.css" type="text/css" /> 
</head>
<body class="theme-light">
    <form id="form1" runat="server">
        <div>
            This is the Terms of Use page
        </div>
    </form>
</body>
</html>

Run the project from Visual Studio and take note of the port used by IIS Express. Start ngrok as indicated in section 4.3 of this chapter, using the port number from IIS Express.

Open Teams (the desktop or web client) and open the App Studio. Open the Manifest editor tab and click on the Create a new app button. In the App details section, define the Short name and Long name of the application (any combination of strings) and click on the Generate button under the Identification section. Then define a Package Name and Version, Description, Long description, Name and Website of the developer. In the App URLs box copy the ngrok URL extended with the file names of the privacy and terms pages.

Click on the Tabs button under Capabilities, and then on the Add button for Add a personal tab. On the new window, define a Name for the tab, a unique string for the Entity ID (it can be any string, but it must be unique), and add the ngrok URL for the content page of the application in the Content URL and Website URL boxes.

Finally, click on the Test and distribute button under the Finish section. If there are errors in the information, the validation will show them. Use the Install button, and Teams will show the Personal Tab application. The manifest can be downloaded, and it will be like the next one.

The application can be found as well in the list generated by the ellipse button on the left side of the client. Also try changing the theme of the Team to check that the theme is applied in the app as well. To uninstall the application, click with the right mouse buttons on the tile of the application, and use the Uninstall option.