| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | API References | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/API-references.md | The following code provides an example of meeting end event payload: * [Teams authentication flow for tabs](../tabs/how-to/authentication/auth-flow-tab.md) * [Apps for Teams meetings](teams-apps-in-meetings.md)+* [Live Share SDK](teams-live-share-overview.md) ## Next steps |
| platform | Teams Apps In Meetings | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-apps-in-meetings.md | The new custom Together Mode scenes feature enables users to collaborate in a me * [Custom Together Mode scenes](~/apps-in-teams-meetings/teams-together-mode.md) * [Enable and configure your apps for Teams meetings](~/apps-in-teams-meetings/enable-and-configure-your-app-for-teams-meetings.md) * [Meeting lifecycle](meeting-app-extensibility.md#meeting-lifecycle)+* [Enhanced collaboration with Live Share SDK](teams-live-share-overview.md) |
| platform | Teams Live Share Capabilities | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-capabilities.md | + + Title: Live Share getting started +description: In this module, learn more about live share SDK capabilities, RSC permissions and ephermal data structures. ++ms.localizationpriority: high ++++++# Live Share capabilities ++The Live Share SDK can be added to your meeting extension's `sidePanel` and `meetingStage` contexts with minimal effort. This article focuses on how to integrate the Live Share SDK into your app and key capabilities of the SDK. ++> [!Note] +> Currently, only scheduled meetings are supported, and all participants must be on the meeting calendar. Meeting types such as, one-on-one calls, group calls, and meet now are currently not supported. +++## Install the JavaScript SDK ++The [Live Share SDK](https://github.com/microsoft/live-share-sdk) is a JavaScript package published on [npm](https://www.npmjs.com/package/@microsoft/live-share), and you can download through npm or Yarn. ++**npm** ++```bash +$ npm install @microsoft/live-share --save +``` ++**Yarn** ++```bash +$ yarn add @microsoft/live-share +``` ++## Register RSC permissions ++To enable the Live Share SDK for your meeting extension, you must first add the following RSC permissions into your app manifest: ++```json +{ + // ...rest of your manifest here + "configurableTabs": [ + { + "configurationUrl": "https://<<BASE_URI_ORIGIN>>/config", + "canUpdateConfiguration": false, + "scopes": [ + "groupchat" + ], + "context": [ + "meetingSidePanel", + "meetingStage" + ] + } + ], + "validDomains": [ + "<<BASE_URI_ORIGIN>>" + ], + "authorization": {ΓÇï + "permissions": {ΓÇï + "resourceSpecific": [ + // ...other permissions hereΓÇï + {ΓÇï + "name": "LiveShareSession.ReadWrite.Chat",ΓÇï + "type": "Delegated" + }, + {ΓÇï + "name": "LiveShareSession.ReadWrite.Group",ΓÇï + "type": "Delegated" + }, + {ΓÇï + "name": "MeetingStage.Write.Chat",ΓÇï + "type": "Delegated" + }, + {ΓÇï + "name": "ChannelMeetingStage.Write.Group",ΓÇï + "type": "Delegated" + } + ]ΓÇï + }ΓÇï + }ΓÇï +} +``` ++## Join a meeting session ++Follow the steps to join a session that is associated with a user's meeting: ++1. Initialize the Teams Client SDK +2. Initialize the [TeamsFluidClient](/javascript/api/@microsoft/live-share/teamsfluidclient) +3. Define the data structures you want to synchronize. For example, `SharedMap` +4. Join the container ++Example: ++```javascript +import * as microsoftTeams from "@microsoft/teams-js"; +import { TeamsFluidClient } from "@microsoft/live-share"; +import { SharedMap } from "fluid-framework"; ++// Initialize the Teams Client SDK +await microsoftTeams.app.initialize(); ++// Setup the Fluid container +const client = new TeamsFluidClient(); +const schema = { + initialObjects: { exampleMap: SharedMap }, +}; +const { container } = await client.joinContainer(schema); ++// ... ready to start app sync logic +``` ++That's all it took to setup your container and join the meeting's session. Now, let's review the different types of _distributed data structures_ that you can use with the Live Share SDK. ++## Fluid distributed data structures ++The Live Share SDK supports any [distributed data structure](https://fluidframework.com/docs/data-structures/overview/) included in Fluid Framework. Here's a quick overview of a few of the different types of objects available: ++| Shared Object | Description | +| -- | -- | +| [SharedMap](https://fluidframework.com/docs/data-structures/map/) | A distributed key-value store. Set any JSON-serializable object for a given key to synchronize that object for everyone in the session. | +| [SharedSegmentSequence](https://fluidframework.com/docs/data-structures/sequences/) | A list-like data structure for storing a set of items (called segments) at set positions. | +| [SharedString](https://fluidframework.com/docs/data-structures/string/) | Distributed-string sequence optimized for editing document text editing. | ++Let's see how `SharedMap` works. In this example, we've used `SharedMap` to build a simple playlist feature. ++```javascript +import { SharedMap } from "fluid-framework"; +// ... +const schema = { + initialObjects: { playlistMap: SharedMap }, +}; +const { container } = await client.joinContainer(schema); +const { playlistMap } = container.initialObjects; ++// Listen for changes to values in the map +playlistMap.on("valueChanged", (changed, local) => { + const video = playlistMap.get(changed.key); + // Update UI with added video +}); ++function onClickAddToPlaylist(video) { + // Add video to map + playlistMap.set(video.id, video); +} +// ... +``` ++> [!Note] +> Core Fluid Framework DDS objects don't support meeting role verification. Everyone in the meeting can change data stored through these objects. ++## Live Share ephemeral data structures ++The Live Share SDK includes a set of new ephemeral `SharedObject` classes, which provide stateful and stateless objects that aren't stored in the Fluid container. For example, if you want to create a laser-pointer feature into your app, such as the popular PowerPoint Live integration, you can use our `EphemeralEvent` or `EphemeralState` objects. ++| Ephemeral Object | Description | +| - | - | +| [EphemeralPresence](/javascript/api/@microsoft/live-share/ephemeralpresence) | See which users are online, set custom properties for each user, and broadcast changes to their presence. | +| [EphemeralEvent](/javascript/api/@microsoft/live-share/ephemeralevent) | Broadcast individual events with any custom data attributes in the payload. | +| [EphemeralState](/javascript/api/@microsoft/live-share/ephemeralstate) | Similar to SharedMap, a distributed key-value store that allows for restricted state changes based on role, for example, the presenter.| ++### EphemeralPresence example ++The `EphemeralPresence` class makes tracking who is attending a meeting easier than ever. When calling the `.start()` or `.updatePresence()` methods, you can assign custom metadata for that user, such as a unique identifier or name. ++Example: ++```javascript +import { EphemeralPresence, PresenceState } from "@microsoft/live-share"; +// ... +const schema = { + initialObjects: { presence: EphemeralPresence }, +}; +const { container } = await client.joinContainer(schema); +const { presence } = container.initialObjects; ++// Listen for changes to presence +presence.on("presenceChanged", (userPresence, local) => { + // Update UI with presence +}); ++// Start tracking presence +presence.start("YOUR_CUSTOM_USER_ID", { + name: "Anonymous", + picture: "DEFAULT_PROFILE_PICTURE_URL", +}); ++function onUserDidLogIn(userName, profilePicture) { + presence.updatePresence(PresenceState.online, { + name: userName, + picture: profilePicture, + }); +} +``` ++### EphemeralEvent example ++`EphemeralEvent` is a great way to send simple events to other clients in a meeting. It's useful for scenarios like sending session notifications. ++```javascript +import { EphemeralEvent } from "@microsoft/live-share"; +// ... +const schema = { + initialObjects: { notifications: EphemeralEvent }, +}; +const { container } = await client.joinContainer(schema); +const { notifications } = container.initialObjects; ++// Listen for incoming notifications +notifications.on("received", (event, local) => { + let notificationToDisplay; + if (local) { + notificationToDisplay = `You ${event.text}`; + } else { + notificationToDisplay = `${event.senderName} ${event.text}`; + } + // Display notification in your UI +}); ++// Start tracking notifications +await notifications.start(); ++notifications.sendEvent({ + senderName: "LOCAL_USER_NAME", + text: "joined the session", +}); +``` ++## Role verification for ephemeral data structures ++Meetings in Teams can range from one-on-one calls to all-hands meetings, and may include members across organizations. Ephemeral objects are designed to support role verification, allowing you to define the roles that are allowed to send messages for each individual ephemeral object. For example, you could choose that only meeting presenters and organizers can control video playback, but still allow guests and attendees to request videos to watch next. ++Example: ++```javascript +import { EphemeralState, UserMeetingRole } from "@microsoft/live-share"; +// ... +const schema = { + initialObjects: { appState: EphemeralState }, +}; +const { container } = await client.joinContainer(schema); +const { appState } = container.initialObjects; ++// Listen for changes to values in the map +appState.on("stateChanged", (state, value, local) => { + // Update local app state +}); ++// Set roles who can change state and start +const allowedRoles = [UserMeetingRole.organizer, UserMeetingRole.presenter]; +appState.start(allowedRoles); ++function onSelectEditMode(documentId) { + appState.changeState("editing", { + documentId, + }); +} ++function onSelectPresentMode(documentId) { + appState.changeState("presenting", { + documentId, + presentingUserId: "LOCAL_USER_ID", + }); +} +``` ++Listen to your customers to understand their scenarios before implementing role verification into your app, particularly for the **Organizer** role. There's no guarantee that a meeting organizer be present in the meeting. As a general rule of thumb, all users will be either **Organizer** or **Presenter** when collaborating within an organization. If a user is an **Attendee**, it's usually an intentional decision on behalf of a meeting organizer. ++## Code samples ++| Sample name | Description | JavaScript | +| -- | - | -- | +| Dice Roller | Enable all connected clients to roll a die and view the result. | [View](https://aka.ms/liveshare-diceroller) | +| Agile Poker | Enable all connected clients to play Agile Poker.| [View](https://aka.ms/liveshare-agilepoker) | ++## Next step ++> [!div class="nextstepaction"] +> [Live Share media capabilities](teams-live-share-media-capabilities.md) ++## See also ++* [GitHub repository](https://github.com/microsoft/live-share-sdk) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Live Share FAQ](teams-live-share-faq.md) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Teams Live Share Faq | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-faq.md | + + Title: Live Share FAQ +description: In this module, learn more about Live Share Frequently Asked Questions. ++ms.localizationpriority: high ++++++# Live Share SDK FAQ ++Get answers to common questions when using Live Share.<br> ++<br> ++<details> ++<summary><b>Can I use my own Azure Fluid Relay service?</b></summary> ++Yes. When constructing the `TeamsFluidClient` class, you can define your own `AzureConnectionConfig`. Live Share associates containers you create with meetings, but you'll need to create your own Azure `ITokenProvider` to sign tokens for your containers and regional requirements. For more information, see Azure [Fluid Relay documentation](/azure/azure-fluid-relay/). ++<br> ++</details> ++<details> ++<summary><b>How long is data stored in Live Share's hosted service accessible?</b></summary> ++Any data sent or stored through Fluid containers created by Live Share's hosted Azure Fluid Relay service is accessible for 24 hours. If you want to persist data beyond 24 hours, you can replace our hosted Azure Fluid Relay service with your own. Alternatively, you can use your own storage provider in parallel to Live Share's hosted service. ++<br> ++</details> ++<details> ++<summary><b>What meeting types does Live Share support?</b></summary> ++Currently, only scheduled meetings are supported and all participants must be on the meeting calendar. Meeting types such as, one-on-one calls, group calls, and meet now aren't supported. ++<br> ++</details> ++<details> ++<summary><b>Will Live Share's media package work with DRM content?</b></summary> ++No. Teams currently doesn't support encrypted media for tab applications. ++<br> ++</details> ++## Have more questions or feedback? ++Submit issues and feature requests to the SDK repository for [Live Share SDK](https://github.com/microsoft/live-share-sdk). Use the `live-share` and `microsoft-teams` tag to post how-to questions about the SDK at [Stack Overflow](https://stackoverflow.com/questions/tagged/live-share+microsoft-teams). ++## See also ++* [GitHub repository](https://github.com/microsoft/live-share-sdk) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Teams Live Share Media Capabilities | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-media-capabilities.md | + + Title: Live Share media capabilities +description: In this module, learn more about Live Share media capabilities, suspensions and wait points, audio ducking, and synchronizing video and audio. ++ms.localizationpriority: high ++++++# Live Share media capabilities ++Video and audio are instrumental parts of the modern world and workplace. We've heard wide ranging feedback that there is more we can do to increase the quality, accessibility, and license protections of watching videos together in meetings. ++The Live Share SDK enables **media synchronization** into any HTML `<video>` and `<audio>` element simpler than ever before. By synchronizing media at the player state and transport controls layer, you can individually attribute views and license, while providing the highest possible quality available through your app. ++## Install ++To add the latest version of the SDK to your application using npm: ++```bash +npm install @microsoft/live-share --save +npm install @microsoft/live-share-media --save +``` ++OR ++To add the latest version of the SDK to your application using [Yarn](https://yarnpkg.com/): ++```bash +yarn add @microsoft/live-share +yarn add @microsoft/live-share-media +``` ++## Media sync overview ++The Live Share SDK has two primary classes related to media synchronization: ++| Classes | Description | +| | | +| [EphemeralMediaSession](/javascript/api/@microsoft/live-share-media/ephemeralmediasession) | Custom ephemeral object designed to coordinate media transport controls and playback state in independent media streams. | +| [MediaPlayerSynchronizer](/javascript/api/@microsoft/live-share-media/mediaplayersynchronizer) | Synchronizes a local HTML Media Element with a group of remote HTML Media Elements for an `EphemeralMediaSession`.| ++Example: ++```html +<body> + <video id="player"> + <source src="YOUR_VIDEO_SRC" type="video/mp4" /> + </video> +</body> +``` ++```javascript +import * as microsoftTeams from "@microsoft/teams-js"; +import { TeamsFluidClient } from "@microsoft/live-share"; +import { EphemeralMediaSession } from "@microsoft/live-share-media"; ++// Initialize the Teams Client SDK +await microsoftTeams.app.initialize(); ++// Setup the Fluid container +const client = new TeamsFluidClient(); +const schema = { + initialObjects: { mediaSession: EphemeralMediaSession }, +}; +const { container } = await client.joinContainer(schema); +const { mediaSession } = container.initialObjects; ++// Get the player from your document and create synchronizer +const player = document.getElementById("player"); +const synchronizer = mediaSession.synchronize(player); ++// Define roles you want to allow playback control and start sync +const allowedRoles = ["Organizer", "Presenter"]; +await mediaSession.start(allowedRoles); +``` ++The `EphemeralMediaSession` automatically listens for changes to the group's playback state and applies changes through the `MediaPlayerSynchronizer`. To avoid playback state changes that a user didn't intentionally initiate, such as a buffer event, we must call transport controls through the synchronizer, rather than directly through the player. ++Example: ++```html +<body> + <video id="player"> + <source src="YOUR_VIDEO_SRC" type="video/mp4" /> + </video> + <div class="player-controls"> + <button id="play-button">Play</button> + <button id="pause-button">Pause</button> + <button id="restart-button">Restart</button> + <button id="change-track-button">Change track</button> + </div> +</body> +``` ++```javascript +// ... ++document.getElementById("play-button").onclick = () => { + synchronizer.play(); +}; ++document.getElementById("pause-button").onclick = () => { + synchronizer.pause(); +}; ++document.getElementById("restart-button").onclick = () => { + synchronizer.seekTo(0); +}; ++document.getElementById("change-track-button").onclick = () => { + synchronizer.setTrack({ + trackIdentifier: "SOME_OTHER_VIDEO_SRC", + }); +}; +``` ++> [!Note] +> While you can use the `EphemeralMediaSession` object to synchronize media directly, using the `MediaPlayerSynchronizer` unless you want more fine tuned control of the synchronization logic. Depending on the player you use in your app, you might want to create a delegate shim to make your web player's interface match the HTML media interface. ++## Suspensions and wait points ++If you want to temporarily suspend synchronization for the `EphemeralMediaSession` object, you can use suspensions. A [MediaSessionCoordinatorSuspension](/javascript/api/@microsoft/live-share-media/ephemeralmediasessioncoordinatorsuspension) object is local by default, which can be helpful in cases where a user might want to catch up on something they missed, take a break, and so on. If the user ends the suspension, synchronization resumes automatically. ++```javascript +// Suspend the media session coordinator +const suspension = mediaSession.coordinator.beginSuspension(); ++// End the suspension when ready +suspension.end(); +``` ++When beginning a suspension, you can also include an optional [CoordinationWaitPoint](/javascript/api/@microsoft/live-share-media/coordinationwaitpoint) parameter, which allows users to define the timestamps in which a suspension should occur for all users. Synchronization won't resume until all users have ended the suspension for that wait point. This is useful for things like adding a quiz or survey at certain points in the video. ++```javascript +// Suspend the media session coordinator +const waitPoint = { + position: 0, + reason: "ReadyUp", // Optional. +}; +const suspension = mediaSession.coordinator.beginSuspension(); +// End the suspension when the user readies up +document.getElementById("ready-up-button").onclick = () => { + // Sync will resume when everyone has ended suspension + suspension.end(); +}; +``` ++## Audio ducking ++The Live Share SDK supports intelligent audio ducking. You can use the _experimental_ feature in your application, add the following to your code: ++```javascript +import * as microsoftTeams from "@microsoft/teams-js"; ++// ... ++let volumeTimer; +microsoftTeams.meeting.registerSpeakingStateChangeHandler((speakingState) => { + if (speakingState.isSpeakingDetected && !volumeTimer) { + volumeTimer = setInterval(() => { + synchronizer.volumeLimiter?.lowerVolume(); + }, 250); + } else if (volumeTimer) { + clearInterval(volumeTimer); + volumeTimer = undefined; + } +}); +``` ++To enable audio ducking, add the following [RSC](/microsoftteams/platform/graph-api/rsc/resource-specific-consent) permissions into your app manifest: ++```json +{ + // ...rest of your manifest here + "authorization": {ΓÇï + "permissions": {ΓÇï + "resourceSpecific": [ + // ...other permissions hereΓÇï + {ΓÇï + "name": "OnlineMeetingIncomingAudio.Detect.Chat",ΓÇï + "type": "Delegated" + }, + {ΓÇï + "name": "OnlineMeetingIncomingAudio.Detect.Group",ΓÇï + "type": "Delegated"ΓÇï + }ΓÇï + ]ΓÇï + }ΓÇï + }ΓÇï +} +``` ++> [!Note] +> The `registerSpeakingStateChangeHandler` API used for audio ducking currently works only for non-local users who are speaking. ++## Code samples ++| Sample name | Description | JavaScript | +| -- | -| --| +| React video | Basic example showing how the EphemeralMediaSession object works with HTML5 video. | [View](https://aka.ms/liveshare-reactvideo) | +| React media template | Enable all connected clients to watch videos together, build a shared playlist, transfer whom is in control, and annotate over the video. | [View](https://aka.ms/liveshare-mediatemplate) | ++## Next step ++> [!div class="nextstepaction"] +> [Agile Poker tutorial](../sbs-teams-live-share.yml) ++## See also ++* [Live Share SDK FAQ](teams-live-share-faq.md) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Reference docs](https://aka.ms/livesharedocs) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Teams Live Share Overview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-overview.md | + + Title: Live Share overview +description: In this module, learn what is Microsoft Live Share SDK and its user scenarios. ++ms.localizationpriority: high ++++++# Live Share SDK ++> [!Note] +> The Live Share SDK is currently available only in [Public Developer Preview](../resources/dev-preview/developer-preview-intro.md). You must be part of the Public Developer Preview for Microsoft Teams to use the Live Share SDK. ++Live Share is an SDK designed to transform Teams apps into collaborative multi-user experiences without writing any dedicated back-end code. The Live Share SDK seamlessly integrates meetings with [Fluid Framework](https://fluidframework.com/). Fluid Framework is a collection of client libraries for distributing and synchronizing shared state. Live Share provides a free, fully managed, and ready to use [Azure Fluid Relay](/azure/azure-relay/relay-what-is-it) backed by the security and global scale of Teams. ++> [!div class="nextstepaction"] +> [Get started](teams-live-share-quick-start.md) ++The Live Share SDK provides a `TeamsFluidClient` class for connecting to a special Fluid Container associated with each meeting in a few lines of code. In addition to the data structures provided by Fluid Framework, Live Share also supports a new set of distributed data structure (DDS) classes to simplify building applications for common meeting scenarios, such as shared media playback. +++## Why build apps using the Live Share SDK? ++Building collaborative apps can be difficult, time consuming, costly, and includes complex compliance requirements at scale. Teams users spend significant amount of time reviewing work with teammates, watching videos together, and brainstorming new ideas through screen sharing. The Live Share SDK enables you to transform your app into something more collaborative with minimal investment. ++Here are some key benefits of the Live Share SDK: ++* Zero-hassle session management and security +* Stateful and stateless distributed data structures +* Media extensions to easily synchronize video and audio +* Respect meeting privileges using role verification +* Free and fully managed service with low latency +* Intelligent audio ducking +++## User scenarios ++|Scenario|Example| +| :- | : | +| Users and their coworkers scheduled a meeting to present an early edit of a marketing video at an upcoming leadership review and want to highlight specific sections for feedback. | Users share the video to the meeting stage and start the video. As needed, the user pauses the video to discuss the scene. Users can take turns drawing over parts of the screen to emphasize key points.| +| You're a project manager for an agile team playing Agile Poker with your team to estimate the amount of work needed for an upcoming sprint.| You share an Agile Poker planning app to the meeting stage that uses the Live Share SDK and play the planning game until the team meets a consensus.| ++> [!IMPORTANT] +> Any data sent or stored through the Live Share SDK's hosted Azure Fluid Relay service is accessible for 24 hours. For more information, see [Live Share FAQ](teams-live-share-faq.md). ++## Next step ++> [!div class="nextstepaction"] +> [Get started](teams-live-share-quick-start.md) ++## See also ++* [GitHub repository](https://github.com/microsoft/live-share-sdk) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Live Share capabilities](teams-live-share-capabilities.md) +* [Live Share media capabilities](teams-live-share-media-capabilities.md) +* [Live Share FAQ](teams-live-share-faq.md) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Teams Live Share Quick Start | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-quick-start.md | + + Title: Live Share quick start +description: In this module, learn how to quickly try the Dice Roller sample ++ms.localizationpriority: high +++++# Quick start guide ++Get started with Live Share SDK using the Dice Roller sample. This get started is an evolution of the [Fluid Framework Quick Start](https://fluidframework.com/docs/start/quick-start/) and is designed to quickly run a Live Share SDK based [Dice Roller sample](https://github.com/microsoft/live-share-sdk/tree/main/samples/01.dice-roller) on your computer's localhost. +++> [!NOTE] +> This guide walks through using Live Share locally in a browser. To learn more about using the SDK in a Teams meeting, try our [Agile Poker tutorial](../sbs-teams-live-share.yml). ++## Set up your development environment ++To get started, install the following: ++* [Node.js](https://nodejs.org/en/download): The Live Share SDK supports Node.js LTS versions 12.17 and later. +* [Latest version of Visual Studio Code](https://code.visualstudio.com/). +* [Git](https://git-scm.com/downloads) ++## Build and run the Dice Roller app ++1. Go to the [Dice Roller](https://github.com/microsoft/live-share-sdk/tree/main/samples/01.dice-roller) sample app. ++1. Clone the [Live Share SDK](https://github.com/microsoft/live-share-sdk) repository to test the sample app: ++ ```bash + $ git clone https://github.com/microsoft/live-share-sdk.git + ``` ++1. Run the following command to go to the Dice Roller sample app folder: ++ ```bash + $ cd live-share-sdk\samples\01.dice-roller + ``` ++1. Run the following command to install the dependency package: ++ ```bash + $ npm install + ``` ++1. Run the following command to start the client and the local server: ++ ```bash + $ npm start + ``` + + A new browser tab opens a `http://localhost:8080` url and the Dice Roller game appears. ++1. Copy the complete URL in the browser, including the ID and paste the URL in a new window or a different browser. ++ A second client for your dice roller application opens. ++1. Open both the windows and select the **Roll** button in one window. The state of the dice changes in both clients. ++ :::image type="content" source="../assets/images/teams-live-share/dice-roller.png" alt-text="Dice Roller multiple tabs"::: + + **Congratulations** you've learned how to build and run an app using the Live Share SDK. ++## Next step ++> [!div class="nextstepaction"] +> [Dice Roller tutorial](teams-live-share-tutorial.md) ++## See also ++* [GitHub repository](https://github.com/microsoft/live-share-sdk) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Live Share capabilities](teams-live-share-capabilities.md) +* [Live Share FAQ](teams-live-share-faq.md) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Teams Live Share Tutorial | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/teams-live-share-tutorial.md | + + Title: Live Share code tutorial +description: In this module, learn how to get started with Live Share SDK and how to build Dice Roller sample using Live Share SDK ++ms.localizationpriority: high +++++# Dice Roller code tutorial ++In the Dice Roller sample app, users are shown a die with a button to roll it. When the die is rolled, the Live Share SDK uses the Fluid Framework to sync the data across clients, so everyone sees the same result. To sync data, perform the following steps in the [app.js](https://github.com/microsoft/live-share-sdk/blob/main/samples/01.dice-roller/src/app.js) file: ++1. [Set up the application](#set-up-the-application) +2. [Join a Fluid container](#join-a-fluid-container) +3. [Write the stage view](#write-the-stage-view) +4. [Connect stage view to Fluid data](#connect-stage-view-to-fluid-data) +5. [Write the side panel view](#write-the-side-panel-view) +6. [Write the settings view](#write-the-settings-view) +++## Set up the application ++Start by importing the required modules. The sample uses the [SharedMap DDS](https://fluidframework.com/docs/data-structures/map/) from the Fluid Framework and the [TeamsFluidClient](/javascript/api/@microsoft/live-share/teamsfluidclient) from the Live Share SDK. The sample supports Teams Meeting Extensibility so we'll need to include the [Teams Client SDK](https://github.com/OfficeDev/microsoft-teams-library-js). Finally, the sample is designed to run both locally and in a Teams meeting so we'll need to include some additional Fluid Framework pieces needed to [test the sample locally](https://fluidframework.com/docs/testing/testing/#azure-fluid-relay-as-an-abstraction-for-tinylicious). + +Applications create Fluid containers using a schema that defines a set of *initial objects* that will be available to the container. The sample uses a SharedMap to store the most recent die value that was rolled. For more information, see [Data modeling](https://fluidframework.com/docs/build/data-modeling/). ++Teams meeting apps require multiple views (content, configuration, and stage). We'll create a `start()` function to help identify the view to render and to perform any initialization that's required. We want our app to support running both locally in a web browser and from within a Teams Meeting so the `start()` function looks for an `inTeams=true` query parameter to determine if it's running in Teams. When running in Teams your application need to call `app.initialize()` prior to calling any other teams-js methods. ++In addition to the `inTeams=true` query parameter, we can use a `view=content|config|stage` query parameter to determine the view that needs to be rendered. ++```js +import { SharedMap } from "fluid-framework"; +import { TeamsFluidClient } from "@microsoft/live-share"; +import { app, pages } from "@microsoft/teams-js"; +import { LOCAL_MODE_TENANT_ID } from "@fluidframework/azure-client"; +import { InsecureTokenProvider } from "@fluidframework/test-client-utils"; ++const searchParams = new URL(window.location).searchParams; +const root = document.getElementById("content"); ++// Define container schema ++const diceValueKey = "dice-value-key"; ++const containerSchema = { + initialObjects: { diceMap: SharedMap } +}; ++function onContainerFirstCreated(container) { + // Set initial state of the rolled dice to 1. + container.initialObjects.diceMap.set(diceValueKey, 1); +} +++// STARTUP LOGIC ++async function start() { ++ // Check for page to display + let view = searchParams.get('view') || 'stage'; ++ // Check if we are running on stage. + if (!!searchParams.get('inTeams')) { ++ // Initialize teams app + await app.initialize(); ++ // Get our frameContext from context of our app in Teams + const context = await app.getContext(); + if (context.page.frameContext == 'meetingStage') { + view = 'stage'; + } + } ++ // Load the requested view + switch (view) { + case 'content': + renderSidePanel(root); + break; + case 'config': + renderSettings(root); + break; + case 'stage': + default: + const { container } = await joinContainer(); + renderStage(container.initialObjects.diceMap, root); + break; + } +} ++start().catch((error) => console.error(error)); +``` ++## Join a Fluid container ++Not all of your apps views will need to be collaborative. The `stage` view _always_ needs collaborative features, the `content` view _may_ need collaborative features, and the `config` view should _never_ need collaborative features. For the views that do need collaborative features you'll need to join a Fluid container associated with the current meeting. ++Joining the container for the meeting is as simple as creating a new [TeamsFluidClient](/javascript/api/@microsoft/live-share/teamsfluidclient) and then calling it's [joinContainer()](/javascript/api/@microsoft/live-share/teamsfluidclient#@microsoft-live-share-teamsfluidclient-joincontainer) method. When running locally you'll need to pass in a custom connection config with a special `LOCAL_MODE_TENANT_ID` but otherwise, join a local container is the same as joining a container in Teams. ++```js +async function joinContainer() { + // Are we running in teams? + let client; + if (!!searchParams.get('inTeams')) { + // Create client + client = new TeamsFluidClient(); + } else { + // Create client and configure for testing + client = new TeamsFluidClient({ + connection: { + tenantId: LOCAL_MODE_TENANT_ID, + tokenProvider: new InsecureTokenProvider("", { id: "123", name: "Test User" }), + orderer: "http://localhost:7070", + storage: "http://localhost:7070", + } + }); + } ++ // Join container + return await client.joinContainer(containerSchema, onContainerFirstCreated); +} +``` ++> [!NOTE] +> When testing locally, the TeamsFluidClient updates the browser URL to contain the ID of the test container that was created. Copying that link to other browser tabs causes the TeamsFluidClient to join the test container that was created. If the modification of the applications URL interferers with the operation of the application, the strategy used to store the test containers ID can be customized using the [setLocalTestContainerId](/javascript/api/@microsoft/live-share/iteamsfluidclientoptions#@microsoft-live-share-iteamsfluidclientoptions-setlocaltestcontainerid) and [getLocalTestContainerId](/javascript/api/@microsoft/live-share/iteamsfluidclientoptions#@microsoft-live-share-iteamsfluidclientoptions-getlocaltestcontainerid) options passed to the TeamsFluidClient. ++## Write the stage view ++Many Teams Meeting Extensibility applications are designed to use React for their view framework, but this isn't required. For example, this sample uses standard HTML/DOM methods to render a view. ++### Start with a static view ++It's easy to create the view using local data without any Fluid functionality, then add Fluid by changing some key pieces of the app. ++The `renderStage` function appends the `stageTemplate` to the passed HTML element, and creates a working dice roller with a random dice value each time the **Roll** button is selected. The `diceMap` is used in the next few steps. ++```js +const stageTemplate = document.createElement("template"); ++stageTemplate["innerHTML"] = ` + <div class="wrapper"> + <div class="dice"></div> + <button class="roll"> Roll </button> + </div> +` +function renderStage(diceMap, elem) { + elem.appendChild(stageTemplate.content.cloneNode(true)); + const rollButton = elem.querySelector(".roll"); + const dice = elem.querySelector(".dice"); ++    rollButton.onclick = () => updateDice(Math.floor(Math.random() * 6)+1); ++    const updateDice = (value) => { +        // Unicode 0x2680-0x2685 are the sides of a die (⚀⚁⚂⚃⚄⚅). +        dice.textContent = String.fromCodePoint(0x267f + value); +    }; + updateDice(1); +} +``` ++## Connect stage view to Fluid data ++### Modify Fluid data ++To begin using Fluid in the application, the first thing to change is what happens when the user selects the `rollButton`. Instead of updating the local state directly, the button updates the number stored in the `value` key of the passed in `diceMap`. Because the `diceMap` is a Fluid `SharedMap`, changes are distributed to all clients. Any changes to the `diceMap` will cause a `valueChanged` event to be emitted, and an event handler can trigger an update of the view. ++This pattern is common in Fluid because it enables the view to behave the same way for both local and remote changes. ++```js +    rollButton.onclick = () => diceMap.set("dice-value-key", Math.floor(Math.random() * 6)+1); +``` ++### Rely on Fluid data ++The next change that needs to be made is to change the `updateDice` function so it no longer accepts an arbitrary value. This means the app can no longer directly modify the local dice value. Instead, the value is retrieved from the `SharedMap` each time `updateDice` is called. ++```js + const updateDice = () => { + const diceValue = diceMap.get("dice-value-key"); +        dice.textContent = String.fromCodePoint(0x267f + diceValue); +    }; + updateDice(); +``` ++### Handle remote changes ++The values returned from `diceMap` are only a snapshot in time. To keep the data up to date as it changes an event handler must be set on the `diceMap` to call `updateDice` each time that the `valueChanged` event is sent. To get a list of events fired and the values passed to those events, see [SharedMap](https://fluidframework.com/docs/data-structures/map/). ++```js + diceMap.on("valueChanged", updateDice); +``` ++## Write the side panel view ++The side panel view, loaded through the tab `contentUrl` with the `sidePanel` frame context, is displayed to the user in a side panel when they open your app within a meeting. The goal of this view is to let a user select content for the app prior to sharing the app to the meeting stage. For the Live Share SDK apps, the side panel view can also be used as a companion experience for the app. Calling [joinContainer()](/javascript/api/@microsoft/live-share/teamsfluidclient#@microsoft-live-share-teamsfluidclient-joincontainer) from the side panel view connects to the same Fluid container the stage view is connected to. This container can then be used to communicate with the stage view. Ensure that you're communicating with everyone's stage view _and_ side panel view. ++The sample's side panel view prompts the user to select the share to stage button. ++```js +const sidePanelTemplate = document.createElement("template"); ++sidePanelTemplate["innerHTML"] = ` + <style> + .wrapper { text-align: center } + .title { font-size: large; font-weight: bolder; } + .text { font-size: medium; } + </style> + <div class="wrapper"> + <p class="title">Lets get started</p> + <p class="text">Press the share to stage button to share Dice Roller to the meeting stage.</p> + </div> +`; ++function renderSidePanel(elem) { + elem.appendChild(sidePanelTemplate.content.cloneNode(true)); +} +``` ++## Write the settings view ++The settings view, loaded through `configurationUrl` in your app manifest, is shown to a user when they first add your app to a Teams Meeting. This view lets the developer configure the `contentUrl` for the tab that is pinned to the meeting based on user input. This page is currently required even if no user input is required to set the `contentUrl`. ++> [!Important] +> The Live Share SDK's [joinContainer()](/javascript/api/@microsoft/live-share/teamsfluidclient#@microsoft-live-share-teamsfluidclient-joincontainer) is not supported in the tab `settings` context. ++The sample's settings view prompts the user to select the save button. ++```js +const settingsTemplate = document.createElement("template"); ++settingsTemplate["innerHTML"] = ` + <style> + .wrapper { text-align: center } + .title { font-size: large; font-weight: bolder; } + .text { font-size: medium; } + </style> + <div class="wrapper"> + <p class="title">Welcome to Dice Roller!</p> + <p class="text">Press the save button to continue.</p> + </div> +`; ++function renderSettings(elem) { + elem.appendChild(settingsTemplate.content.cloneNode(true)); ++ // Save the configurable tab + pages.config.registerOnSaveHandler(saveEvent => { + pages.config.setConfig({ + websiteUrl: window.location.origin, + contentUrl: window.location.origin + '?inTeams=1&view=content', + entityId: 'DiceRollerFluidLiveShare', + suggestedDisplayName: 'DiceRollerFluidLiveShare' + }); + saveEvent.notifySuccess(); + }); ++ // Enable the Save button in config dialog + pages.config.setValidityState(true); +} +``` ++## Test locally ++You can test your app locally, using `npm run start`. For more information, see [Quick Start Guide](./teams-live-share-quick-start.md). ++## Test in Teams ++After you've started running your app locally with `npm run start`, you can then test your app on Teams. If you want to test your app without deployment, download and use the [`ngrok`](https://ngrok.com/) tunneling service. ++### Create a ngrok tunnel to allow Teams to reach your app ++1. [Download ngrok](https://ngrok.com/download). ++1. Use ngrok to create a tunnel with port 8080. Run the following command: ++ ``` + `ngrok http 8080 --host-header=localhost` + ``` ++ A new ngrok terminal opens with a new url, for example `https:...ngrok.io`. The new URL is the tunnel that points to your app, which needs to be updated in your app `manifest.json`. ++### Create the app package to sideload into Teams ++1. Go to the Dice Roller sample folder `\live-share-sdk\samples\01.dice-roller` on your computer. You can also check the [`.\manifest\manifest.json`](https://github.com/microsoft/live-share-sdk/tree/main/samples/01.dice-roller/manifest) from the Dice Roller sample on GitHub. ++1. Open manifest.json and update the configuration URL. ++ Replace `https://<<BASE_URI_DOMAIN>>` with your http endpoint from ngrok. ++1. You can update the following fields: + * Set `developer.name` to your name. + * Update `developer.websiteUrl` with your website. + * Update `developer.privacyUrl` with your privacy policy. + * Update `developer.termsOfUseUrl` with your terms of use. ++1. Zip the contents of the manifest folder to create `manifest.zip`. Ensure that the `manifest.zip` contains only the `manifest.json` source file, `color` icon, and the `outline` icon. ++ 1. On Windows, select all files in `.\manifest` directory and compress them. + + > [!NOTE] + > + > * Do not zip the containing folder. + > * Give your zip file a descriptive name. For example, `DiceRollerLiveShare`. + + For more information on manifest, visit the [Teams manifest documentation](../resources/schem) ++### Sideload your app into a meeting ++1. Open Teams. ++1. Schedule a meeting from the calendar in Teams. Ensure you invite atleast one attendee to the meeting. ++1. Join the meeting. ++1. In the meeting window at the top, select **+ Apps** > **Manage apps**. ++1. In the **Manage apps** pane, select **Upload a custom app**. ++ 1. If you don't see the option to **Upload a custom app**, follow [instructions](/microsoftteams/teams-custom-app-policies-and-settings) to enable custom apps in your tenant. ++1. Select and upload the `manifest.zip` file from your computer. ++1. Select **Add** to add your sample app into the meeting. ++1. Select **+ Apps**, type Dice Roller in the **Find an app** search box. ++1. Select the app to activate it in the meeting. ++1. Select **Save**. ++ The Dice Roller app is added to the Teams meeting panel. ++1. In the side panel, select the share to stage icon. Teams starts a live sync with the users on the meeting stage in the meeting. ++ :::image type="content" source="../assets/images/teams-live-share/teams-live-share-to-stage.png" alt-text="share to stage icon"::: ++ You should now see dice-roller on the meeting stage. ++ :::image type="content" source="../assets/images/teams-live-share/teams-live-share-meeting-stage.png" alt-text="meeting stage image"::: ++Users invited to the meeting can see your app on stage when they join the meeting. ++## Deployment ++After you're ready to deploy your code, you can use [Teams Toolkit](../toolkit/provision.md#provision-using-teams-toolkit) or the [Teams Developer Portal](https://dev.teams.microsoft.com/apps) to provision and upload your app's zip file. ++> [!NOTE] +> You need to add your provisioned appId to the `manifest.json` before uploading or distributing the app. ++## Code samples ++| Sample name | Description | JavaScript | +| :- | - | | +| Dice Roller | Enable all connected clients to roll a die and view the result. | [View](https://github.com/microsoft/live-share-sdk/tree/main/samples/01.dice-roller) | ++## Next step ++> [!div class="nextstepaction"] +> [Core capabilities](teams-live-share-capabilities.md) ++## See also ++* [GitHub repository](https://github.com/microsoft/live-share-sdk) +* [Live Share SDK reference docs](/javascript/api/@microsoft/live-share/) +* [Live Share Media SDK reference docs](/javascript/api/@microsoft/live-share-media/) +* [Live Share FAQ](teams-live-share-faq.md) +* [Teams apps in meetings](teams-apps-in-meetings.md) |
| platform | Publish | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/concepts/deploy-and-publish/appsource/publish.md | When you feel your app is production ready, you can begin the process of getting * **During design phase** - Review the [store validation guidelines](prepare/teams-store-validation-guidelines.md) early in your app's life cycle (design phase) to ensure that you build your app in alignment with the store requirements. If you build your app in line with these guidelines, this will prevent any rework due to non-adherence to store policies. + Review the [store validation guidelines](~/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines.md) early in your app's life cycle (design phase) to ensure that you build your app in alignment with the store requirements. If you build your app in line with these guidelines, this will prevent any rework due to non-adherence to store policies. * **Prior to app submission** When you feel your app is production ready, you can begin the process of getting :::image type="content" source="../../../assets/images/submission/teams-validation-developer-portal.png" alt-text="Teams store app validation in Developer Portal" lightbox="../../../assets/images/submission/teams-validation-developer-portal.png"::: - 1. Self-test your app thoroughly prior to app submission to ensure it adheres with store policies. Sideload the app in Teams and test the end-to-end user flows for your app. Ensure the functionality works as expected, links aren't broken, user experience isn't blocked, and any limitations are clearly highlighted. + 1. Self-test your app thoroughly prior to app submission to ensure it adheres with store policies. Sideload the app in Teams and test the end to end user flows for your app. Ensure the functionality works as expected, links aren't broken, user experience isn't blocked, and any limitations are clearly highlighted. 1. Test your app across desktop, web, and mobile clients. Ensure that the app is responsive across different form factors.-+ 1. Complete [publisher verification](/azure/active-directory/develop/publisher-verification-overview) before you submit your app. If you run into any issues, you can create a [support ticket](/azure/marketplace/partner-center-portal/support) for resolution. 1. As you prepare for app submission, [follow the checklist](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/submission-checklist) and include the following details as part of your submission package: - 1. Thoroughly verified app package. + 1. Thoroughly verified app package. - 1. Working admin and non-admin user credentials to test your app functionality (if your app offers a premium subscription model). + 1. Working admin and non-admin user credentials to test your app functionality (if your app offers a premium subscription model). - 1. Test instructions detailing app functionality and supported scenarios. + 1. Test instructions detailing app functionality and supported scenarios. - 1. Setup instructions if your app requires additional configuration to access app functionality. Alternately, if your app requires complex configuration, you can also provide a [provisioned demo tenant](/office/developer-program/microsoft-365-developer-program-get-started) with admin access so that our validators can skip the configuration steps. + 1. Setup instructions if your app requires additional configuration to access app functionality. Alternately, if your app requires complex configuration, you can also provide a [provisioned demo tenant](/office/developer-program/microsoft-365-developer-program-get-started) with admin access so that our validators can skip the configuration steps. - 1. Link to a demo video recording key user flow for your app. This is highly recommended. + 1. Link to a demo video recording key user flow for your app. This is highly recommended. * **Post app submission** When you feel your app is production ready, you can begin the process of getting * Avoid changing app functionality during the validation process. This might lead to discovery of new issues and increase the time it takes to approve your app. +## Additional tips for rapid approval to publish your app linked to a SaaS offer ++* **During design phase** ++ Review the [store validation guidelines specific to apps published with linked SaaS offers](~/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines.md#apps-linked-to-saas-offer) early in your app's life cycle (design phase) to ensure that you build your app in alignment with the store requirements and [Microsoft Commercial Marketplace policies applicable to Teams apps linked to SaaS offers](/legal/marketplace/certification-policies#11405-teams-app-linked-to-software-as-a-service-saas-offers). If you build your app in line with these guidelines, this will prevent any rework due to non-adherence to store policies. ++* **Prior to app submission** ++ 1. As you prepare for app submission, ensure the following: ++ 1. Your app is linked to a live (already published) SaaS offer on AppSource with at least one plan with pricing information. ++ 1. You have correctly mentioned the `subscriptionOffer` details in your app manifest in the format `publisherId.offerId`. ++ 1. You must ensure your linked SaaS offer is designed to support licenses assigned on a named [per user model](/azure/marketplace/create-new-saas-offer-plans). Linked SaaS offers that support other pricing models such as flat rate are currently not accepted for publishing to the Teams store. ++ 1. Include test instructions or setup instructions or link to a demo video detailing app functionality and supported scenarios and any additional information to enable our testers to easily understand your SaaS portal workflows. ++ 1. You must thoroughly [self-test](~/concepts/deploy-and-publish/appsource/prepare/test-preview-for-monetized-apps.md) the end to end purchase and license management workflows before you submit your app linked to a SaaS offer for validation, ensure the following: ++ 1. Both admin and non-admin users can place an order and confirm the purchase of your subscription. Purchasers can navigate to the SaaS application landing page by selecting **Setup Now** in the Microsoft Admin Center. Test and ensure that your purchasers can activate and configure their subscription on your SaaS application. Messaging on your SaaS application should provide enough and clear information on the way forward to a purchaser. ++ 1. The **Manage Subscriptions** section in Microsoft Admin Center shows the correct details of the subscriptions brought by your test users. Subscription status, number of licenses, and other details must be accurate. ++ 1. Buying and removal of license workflows are working as expected. Ensure purchasers can increase the number of licenses from Microsoft Admin Center. Ensure license count and assignment on your SaaS application reflects respective licenses and the right assignees. Also, ensure your SaaS application provides a way to take away a license from an user. Post removal of a license, ensure remaining assignments and count remain intact on your SaaS application and the correct details are reflected in the Microsoft Admin Center. ++ 1. Subscription cancellation is working as expected. Purchasers can cancel a subscription. Post cancellation, check if the correct subscription status is reflected in the Microsoft Admin Center and your SaaS application. Verify that the purchaser has lost access to the subscription after successful cancellation. ++ 1. Re-purchasing a subscription is seamless. After cancellation of an active subscription, thoroughly test to ensure purchasers can repurchase the subscription. ++ 1. Purchasers can change their subscribed plan. After the plan is modified, users can access the upgraded or downgraded plan features. ++ 1. Your SaaS application contains license management features. Purchasers must be able to assign, modify, and re-assign available licenses to users. Check if purchasers can add or remove users to manage the licenses. + + 1. You must test and ensure both minimum and bulk license purchase flows are working as expected. + + 1. You must ensure users who are assigned licenses have access to the accurate purchased plan features described in your planΓÇÖs listing. + ## See also * [Publishing to Microsoft 365 App Stores](/office/dev/store/) |
| platform | Feedback | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/feedback.md | Submit issues and ask general questions related to SDK and samples using the com | **Teams Toolkit or TeamsFx SDK and CLI issues** | <ul><li> :::image type="icon" source="assets/icons/GitHub-icon.png" border="false"::: [GitHub Issues](https://github.com/OfficeDev/TeamsFx/issues): Create new issues on the [TeamsFx (Microsoft Teams Framework) GitHub repository](https://github.com/OfficeDev/TeamsFx) to report issues or raise feature request. We recommend using GitHub issues for queries and to receive community help. <li> :::image type="icon" source="assets/icons/stack-overflow-icon.png" border="false"::: [Stack Overflow](https://stackoverflow.com/questions/tagged/teams-toolkit): Use the `teams-toolkit` tag to post questions. Follow the Stack Overflow guidelines such as provide a descriptive title, a concise problem statement, and details to reproduce the issue. Feature requests or broad questions are off-topic. </li> </ul> | | **Bot and Message extension SDK issues or suggestions** | Submit issues and feature requests to the SDK repository for your bot's language ([C#](https://github.com/Microsoft/botbuilder-dotnet/), [JavaScript](https://github.com/Microsoft/botbuilder-js), or [Python](https://github.com/Microsoft/botbuilder-python)). Post How-to questions at [Stack Overflow](https://stackoverflow.com/questions/tagged/botframework%20microsoft-teams) using the `botframework` and `microsoft-teams` tag. | | **Tab SDK issues or suggestions** | Submit issues and feature requests to the SDK repository for [Microsoft Teams JavaScript Library](https://github.com/OfficeDev/microsoft-teams-library-js/issues). Use the `microsoft-teams` tag to post how-to questions about the SDK at [Stack Overflow](https://stackoverflow.com/questions/tagged/microsoft-teams). |+| **Live Share SDK issues or suggestions** | Submit issues and feature requests to the SDK repository for [Live Share SDK](https://github.com/microsoft/live-share-sdk). Use the `live-share` and `microsoft-teams` tag to post how-to questions about the SDK at [Stack Overflow](https://stackoverflow.com/questions/tagged/live-share+microsoft-teams). | ### Documentation feedback |
| platform | Get Started Overview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/get-started/get-started-overview.md | If you are already familiar with Yeoman workflow, you may prefer using [YoTeams Now, let's build your first Teams app. But first, pick your language (or framework) and prepare your development environment. > [!div class="nextstepaction"]-> [Build a Teams app with JavaScript using React](../sbs-gs-javascript.yml) +> [Build a Teams tab app with JavaScript using React](../sbs-gs-javascript.yml) +> [!div class="nextstepaction"] +> [Build a Teams bot app with JavaScript using React](../sbs-gs-bot.yml) +> [!div class="nextstepaction"] +> [Build a Teams message extension app with JavaScript using React](../sbs-gs-msgext.yml) > [!div class="nextstepaction"] > [Build a Teams app with Blazor](../sbs-gs-blazorupdate.yml) > [!div class="nextstepaction"] Now, let's build your first Teams app. But first, pick your language (or framewo > [Build a Teams app with C# or .NET](../sbs-gs-csharp.yml) > [!div class="nextstepaction"] > [Build a Teams app with Node.js](../sbs-gs-nodejs.yml)+> [!div class="nextstepaction"] +> [Build notification bot with JavaScript](../sbs-gs-notificationbot.yml) +> [!div class="nextstepaction"] +> [Build command bot with JavaScript](../sbs-gs-commandbot.yml) +> [!div class="nextstepaction"] ## See also |
| platform | Glossary | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/get-started/glossary.md | Common terms and definitions used in Teams Developer Documentation. | [Teams Toolkit](../toolkit/teams-toolkit-fundamentals.md) | The Microsoft Teams Toolkit enables you to create custom Teams apps directly within the Visual Studio Code environment. | | [TeamsFx](../toolkit/teamsfx-cli.md) | TeamsFx is a text-based command line interface that accelerates Teams application development. It's also called TeamsFx CLI.| | [TeamsFx SDK](../toolkit/teamsfx-sdk.md) | TeamsFx SDK is pre-configured in scaffolded project using TeamsFx toolkit or CLI. |-| [TeamsJS SDK](../tabs/how-to/using-teams-client-sdk.md) | TeamsJS SDK enables you to create hosted experiences in Teams. The functionalities in [latest version](~/m365-apps/using-teams-client-sdk-preview.md) extend Teams app to run in Outlook and Office. | +| [TeamsJS SDK](../tabs/how-to/using-teams-client-sdk.md) | TeamsJS SDK enables you to create hosted experiences in Teams. Starting with TeamsJS v.2.0.0, you can extend Teams apps to run in Outlook and Office. | | [Teams Mobile](../concepts/design/plan-responsive-tabs-for-teams-mobile.md) | Microsoft Teams available as a mobile app. | | [Teams store](../concepts/deploy-and-publish/appsource/publish.md) | A store landing page that brings apps to users in a single place. The apps are categorized by usage, industry, and more. An app must follow Store validation guidelines and obtain an approval before it's available to users via the Teams store. <br>**See also**: [Store validation guidelines](#s) | | [Teams workbench](../sbs-gs-spfx.yml) | A workbench in Visual Studio Code used at build for Teams apps created using SPFx and Teams Toolkit. <br>**See also**: [Workbench](#w); [Local workbench](#l) | |
| platform | Azure Provisioning Instructions | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/includes/get-started/azure-provisioning-instructions.md | ## Deploy your app to Azure Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning). Then, your app's code is copied into the created cloud resources. For this tutorial, you will deploy the tab app.- -> <details> -> <summary>What's the difference between Provision and Deploy?</summary> -> -> The **Provision** step creates resources in Azure and Microsoft 365 for your app, but no code (HTML, CSS, JavaScript, etc.) is copied to the resources. The **Deploy** step copies the code for your app to the resources you created during the provision step. It is common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it is separate from the deployment step. +<br> +<br> +<details> +<summary>What's the difference between Provision and Deploy?</summary> +<br> +The <b>Provision</b> step creates resources in Azure and Microsoft 365 for your app, but no code (HTML, CSS, JavaScript, etc.) is copied to the resources. The <b>Deploy</b> step copies the code for your app to the resources you created during the provision step. It is common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it is separate from the deployment step. </details>+<br> # [Visual Studio Code](#tab/vscode) Select the Teams Toolkit :::image type="icon" source="~/assets/images/teams-tool 1. Select **Provision**. - :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/provision-warning.png" alt-text="Screenshot of the provisioning dialog." border="false"::: + :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/provision-warning.png" alt-text="Screenshot of the provisioning dialog." border="true"::: The provisioning process creates resources in the Azure cloud. It may take some time. You can monitor the progress by watching the dialogs in the bottom-right corner. After a few minutes, you see the following notice: - :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/deploy-provision-success.png" alt-text="Screenshot showing the provisioning complete dialog." border="false"::: + :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/deploy-provision-successmsg.png" alt-text="Screenshot showing the provisioning complete dialog." border="false"::: If you want you can view the provisioned resources. For this tutorial, you don't need to view resources. Once the provisioning and deployment steps are complete: 1. Open the debug panel (**Ctrl+Shift+D** / **⌘⇧-D** or **View > Run**) from Visual Studio Code. 1. Select **Launch Remote (Edge)** from the launch configuration drop-down.-1. Select the Play button to launch your app from Azure. +1. Select the **Start debugging (F5)** to launch your app from Azure. :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/launch-remote.png" alt-text="Screenshot showing the launch app remotely." border="false"::: -1. Select **Add**. +1. Select **Add** when prompted to sideload the app onto Teams on your local machine. ++ :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/add-bot-debug.png" alt-text="Screenshot showing the bot is being added on Teams client."::: ++ You can type `welcome` to show an introduction card, and type `learn` to go to adaptive card and bot command documentation. - :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/remote-app-client.png" alt-text="Screenshot showing the app being installed." border="false"::: + :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/azure-deployed-app.png" alt-text="Screenshot showing the learn card in the bot on Teams client."::: - Your app is loaded on the Azure site. - :::image type="content" source="~/assets/images/teams-toolkit-v2/deploy-azure/azure-deployed-app.png" alt-text="Screenshot showing the app being installed." border="false"::: - Congratulations! Your tab app is now running remotely from Azure! |
| platform | Extend M365 Teams Message Extension | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/extend-m365-teams-message-extension.md | Title: Extend a Teams message extension across Microsoft 365 description: Here's how to update your search-based Teams message extension to run in Outlook Previously updated : 02/11/2022 Last updated : 05/24/2022 ms.localizationpriority: high # Extend a Teams message extension across Microsoft 365 -> [!NOTE] -> *Extending a Teams message extension across Microsoft 365* is currently available only in [public developer preview](../resources/dev-preview/developer-preview-intro.md). Features included in preview may not be complete, and may undergo changes before becoming available in the public release. They are provided for testing and exploration purposes only. They should not be used in production applications. --Search-based [message extensions](/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions) allow users to search an external system and share results through the compose message area of the Microsoft Teams client. By [extending your Teams apps across Microsoft 365 (preview)](overview.md), you can now bring your search-based Teams message extensions to Outlook for Windows desktop and web experiences. +Search-based [message extensions](/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions) allow users to search an external system and share results through the compose message area of the Microsoft Teams client. By [extending your Teams apps across Microsoft 365](overview.md), you can now bring production search-based Teams message extensions to preview audiences in Outlook for Windows desktop and outlook.com. The process to update your search-based Teams message extension to run Outlook involves these steps: The process to update your search-based Teams message extension to run Outlook i > * Add an Outlook channel for your bot > * Sideload your updated app in Teams -The rest of this guide will walk you through these steps and show you how to preview your message extension in both Outlook for Windows desktop and web. +The rest of this guide will walk you through these steps and show you how to preview your message extension in both Outlook for Windows desktop and outlook.com. ## Prerequisites To complete this tutorial, you'll need: * A Microsoft 365 Developer Program sandbox tenant-* Your sandbox tenant enrolled in *Office 365 Targeted Releases* -* A test environment with Office apps installed from the Microsoft 365 Apps *beta channel* -* Microsoft Visual Studio Code with the Teams Toolkit (Preview) extension (Optional) +* Enrollment in *Office 365 Targeted Releases* for your sandbox tenant +* A test environment with Office apps installed from the Microsoft 365 Apps *Beta Channel* +* (Optional) Microsoft Visual Studio Code with the Teams Toolkit extension > [!div class="nextstepaction"]-> [Install prerequisites](prerequisites.md) +> [Publish Teams apps extended for Microsoft 365](publish.md) ## Prepare your message extension for the upgrade -If you have an existing message extension, make a copy or a branch of your production project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID). +If you have an existing message extension in production, make a copy or a branch of your project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID, for testing). ++If you'd like to use sample code to complete the full tutorial on updating an existing Teams app, follow the setup steps in [Teams message extension search sample](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/javascript_nodejs/50.teams-messaging-extensions-search) to quickly build a Microsoft Teams search-based message extension. ++Alternately, you can use the ready-made Outlook-enabled app in the following section and skip the [*Update the app manifest*](#update-the-app-manifest) portion of this tutorial. ++### Quickstart ++To start with a [sample message extension](https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/NPM-search-connector-M365) that's already enabled to run in Outlook, use Teams Toolkit extension for Visual Studio Code. ++1. From Visual Studio Code, open the command palette (`Ctrl+Shift+P`), type `Teams: Create a new Teams app`. +1. Select **Create a new Teams app** option. +1. Select **Search-based message extension** to download sample code for a Teams message extension using the latest Teams app manifest (version `1.13`). ++ :::image type="content" source="images/toolkit-palatte-search-sample.png" alt-text="Type 'Create a new Teams app' VS Code command palette to list Teams sample options"::: ++ The sample is also available as *NPM Search Connector* in the Teams Toolkit Samples gallery. From the Teams Toolkit pane, select *Development* > *View samples* > **NPM Search Connector**. -If you'd like to use sample code to complete this tutorial, follow the setup steps in [Teams message extension search sample](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/javascript_nodejs/50.teams-messaging-extensions-search) to quickly build a Microsoft Teams search-based message extension. Or, you can start with the same [Teams Message Extensions Search sample updated for TeamsJS SDK v2 Preview](https://github.com/OfficeDev/TeamsFx-Samples/tree/v2/NPM-search-connector-M365) and proceed to [Preview your message extension in Outlook](#preview-your-message-extension-in-outlook). The updated sample is also available within Teams Toolkit extension: *Development* > *View samples* > **NPM Search Connector**. + :::image type="content" source="images/toolkit-search-sample.png" alt-text="NPM Search Connector sample in Teams Toolkit Samples gallery"::: +1. Select a location on your local machine for the workspace folder. +1. Open the command palette (`Ctrl+Shift+P`) and type `Teams: Provision in the cloud` to create the required app resources (Azure App Service, App Service plan, Azure Bot, and Managed Identity) in your Azure account. +1. Open the command palette (`Ctrl+Shift+P`) and type `Teams: Deploy to the cloud` to deploy the sample code to the provisioned resources in Azure and start the app. ++From here, you can skip ahead to [Add an Outlook channel for your bot](#add-an-outlook-channel-for-your-bot) to complete the final step of enabling the Teams message extension to work in Outlook. (The app manifest is already referencing the correct version, so no updates are necessary.) ## Update the app manifest -You'll need to use the [Teams developer preview manifest](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview) schema and the `m365DevPreview` manifest version to enable your Teams message extension to run in Outlook. +You'll need to use the [Teams developer manifest](../resources/schem) schema version `1.13` to enable your Teams message extension to run in Outlook. You have two options for updating your app manifest: # [Teams Toolkit](#tab/manifest-teams-toolkit) -1. Open the *Command palette*: `Ctrl+Shift+P` -1. Run the `Teams: Upgrade Teams manifest to support Outlook and Office apps` command and select your app manifest file. Changes will be made in place. +1. Open the command palette: `Ctrl+Shift+P`. +1. Run the `Teams: Upgrade Teams manifest` command and select your app manifest file. Changes will be made in place. # [Manual steps](#tab/manifest-manual) Open your Teams app manifest and update the `$schema` and `manifestVersion` with ```json {- "$schema" : "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json", - "manifestVersion" : "m365DevPreview" + "$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json", + "manifestVersion" : "1.13" } ``` -If you used Teams Toolkit to create your message extension app, you can use it to validate the changes to your manifest file and identify any errors. Open the command palette `Ctrl+Shift+P` and find **Teams: Validate manifest file** or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code). -+If you used Teams Toolkit to create your message extension app, you can use it to validate the changes to your manifest file and identify any errors. Open the command palette `Ctrl+Shift+P` and find **Teams: Validate manifest file**. ## Add an Outlook channel for your bot For users to interact with your message extension from Outlook, you'll need to a 1. From *Settings*, select **Channels**. -1. Click on **Outlook**, select the **Message extensions** tab, then click **Save**. +1. Under *Available channels*, select **Outlook**. Select the **Message extensions** tab, then **Apply**. :::image type="content" source="images/azure-bot-channel-message-extensions.png" alt-text="Add an Outlook 'Message Extensions' channel for your bot from the Azure Bot Channels pane"::: -1. Confirm that your Outlook channel is listed along with Microsoft Teams in your bot's **Channels** pane: +1. Confirm that your Outlook channel is listed along with Microsoft Teams in your bot's **Channels** pane. :::image type="content" source="images/azure-bot-channels.png" alt-text="Azure Bot Channels pane listing both Microsoft Teams and Outlook channels"::: ## Update Microsoft Azure Active Directory (Azure AD) app registration for SSO > [!NOTE]-> You can skip the step if you're using [Teams message extension search sample](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/javascript_nodejs/50.teams-messaging-extensions-search), as the scenario doesn't involve Azure Active Directory (AAD) Single Sign-On authentication. +> You can skip the step if you're using the [sample app](#quickstart) provided in this tutorial, as the scenario doesn't involve Azure Active Directory (AAD) Single Sign-On authentication. -Azure Active Directory Single-sign on (SSO) for message extensions works the same way in Outlook [as it does in Teams](/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots), however you need to add several client application identifiers to the Azure AD app registration of your bot in your tenant's *App registrations* portal. +Azure Active Directory (AD) Single-sign on (SSO) for message extensions works the same way in Outlook [as it does in Teams](/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots). However you need to add several client application identifiers to the Azure AD app registration of your bot in your tenant's *App registrations* portal. 1. Sign in to [Azure portal](https://portal.azure.com) with your sandbox tenant account. 1. Open **App registrations**. 1. Select the name of your application to open its app registration. 1. Select **Expose an API** (under *Manage*).+1. In the **Authorized client applications** section, ensure all of the following `Client Id` values are listed: -In the **Authorized client applications** section, ensure all of the following `Client Id` values are listed: --|Microsoft 365 client application | Client ID | -|--|--| -|Teams desktop and mobile |1fec8e78-bce4-4aaf-ab1b-5451cc387264 | -|Teams web |5e3ce6c0-2b1f-4285-8d4b-75ee78787346 | -|Outlook desktop | d3590ed6-52b3-4102-aeff-aad2292ab01c | -|Outlook Web Access | 00000002-0000-0ff1-ce00-000000000000 | -|Outlook Web Access | bc59ab01-8403-45c6-8796-ac3ef710b3e3 | + |Microsoft 365 client application | Client ID | + |--|--| + |Teams desktop and mobile |1fec8e78-bce4-4aaf-ab1b-5451cc387264 | + |Teams web |5e3ce6c0-2b1f-4285-8d4b-75ee78787346 | + |Outlook desktop | d3590ed6-52b3-4102-aeff-aad2292ab01c | + |Outlook Web Access | 00000002-0000-0ff1-ce00-000000000000 | + |Outlook Web Access | bc59ab01-8403-45c6-8796-ac3ef710b3e3 | ## Sideload your updated message extension in Teams The final step is to sideload your updated message extension ([app package](/microsoftteams/platform/concepts/build-and-test/apps-package)) in Microsoft Teams. Once completed, your message extension will appear in your installed *Apps* from the compose message area. -1. Package your Teams application (manifest and app [icons](/microsoftteams/platform/resources/schema/manifest-schema#icons)) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the **Zip Teams metadata package** option in the *Deployment* menu of Teams Toolkit: +1. Package your Teams application (manifest and app [icons](/microsoftteams/platform/resources/schema/manifest-schema#icons)) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the **Zip Teams metadata package** option in the *Deployment* menu of Teams Toolkit. :::image type="content" source="images/toolkit-zip-teams-metadata-package.png" alt-text="'Zip Teams metadata package' option in Teams Toolkit extension for Visual Studio Code"::: -1. Log in to Teams with your sandbox tenant account, and verify you are on the *Public Developer Preview* by clicking on the ellipsis (**...**) menu by your user profile and opening **About** to check that the *Developer preview* option is toggled on. -- :::image type="content" source="images/teams-dev-preview.png" alt-text="From Teams ellipses menu, open 'About' and verify 'Developer Preview' option is checked"::: +1. Sign in to Teams with your sandbox tenant account, and toggle into *Developer Preview* mode. Select the ellipsis (**...**) menu by your user profile, then select: **About** > **Developer preview**. -1. Open the *Apps* pane, and click **Upload a custom app** and then **Upload for me or my teams**. + :::image type="content" source="images/teams-dev-preview.png" alt-text="From Teams ellipses menu, open 'About', and select 'Developer Preview' option"::: - :::image type="content" source="images/teams-upload-custom-app.png" alt-text="'Upload a custom app' button in the Teams 'Apps' pane"::: +1. Select **Apps** to open the **Manage your apps** pane. Then select **Publish an app**. -1. Select your app package and click *Open*. + :::image type="content" source="images/teams-manage-your-apps.png" alt-text="Open the 'Manage your apps' pane and select 'Publish an app'"::: -Once sideloaded through Teams, your message extension will be available in Outlook on the web. +1. Choose **Upload a custom app** option, select your app package, and install (*Add*) it to your Teams client. -## Preview your message extension in Outlook + :::image type="content" source="images/teams-upload-custom-app.png" alt-text="'Upload a custom app' option in Teams"::: -You're now ready to test your message extension running in Outlook on Windows desktop and the web. While your updated message extension will continue to run in Teams with full [feature support for message extensions](/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions), there are limitations in this early preview of the Outlook-enabled experience to be aware of: +After it's sideloaded through Teams, your message extension will be available in outlook.com and Outlook for Windows desktop. -* Message extensions in Outlook are limited to the mail [*compose* context](/microsoftteams/platform/resources/schema/manifest-schema#composeextensions). Even if your Teams message extension includes `commandBox` as a *context* in its manifest, the current preview is limited to the mail composition (`compose`) option. Invoking a message extension from the global Outlook *Search* box is not supported. -* [Action-based message extension](/microsoftteams/platform/messaging-extensions/how-to/action-commands/define-action-command?tabs=AS) commands are not supported in Outlook. If your app has both search- and action-based commands, it will surface in Outlook but the action menu will not be available. -* Insertion of more than five [Adaptive Cards](/microsoftteams/platform/task-modules-and-cards/cards/design-effective-cards?tabs=design) in an email is not supported; Adaptive Cards v1.4 and later are not supported. -* [Card actions](/microsoftteams/platform/task-modules-and-cards/cards/cards-actions?tabs=json) of type `messageBack`, `imBack`, `invoke`, and `signin` are not supported for inserted cards. Support is limited to `openURL`: on click, the user will be redirected to the specified URL in a new tab. +## Preview your message extension in Outlook -As you test your message extension, you can identify the source (originating from Teams versus Outlook) of bot requests by the [channelId](https://github.com/Microsoft/botframework-sdk/blob/main/specs/botframework-activity/botframework-activity.md#channel-id) of the [Activity](https://github.com/Microsoft/botframework-sdk/blob/main/specs/botframework-activity/botframework-activity.md) object. When a user performs a query, your service receives a standard Bot Framework `Activity` object. One of the properties in the Activity object is `channelId`, which will have the value of `msteams` or `outlook`, depending from where the bot request originates. For more, see [Search based message extensions SDK](/microsoftteams/platform/resources/messaging-extension-v3/search-extensions). +Here's how to test your message extension running in Outlook on Windows desktop and the web. ### Outlook on the web To preview your app running in Outlook on the web: -1. Log in to [outlook.com](https://www.outlook.com) using credentials for your test tenant. +1. Sign in to [outlook.com](https://www.outlook.com) using credentials for your test tenant. 1. Select **New message**. 1. Open **More apps** flyout menu on the bottom of the composition window. + :::image type="content" source="images/outlook-web-compose-more-apps.png" alt-text="Click on the 'More apps' menu on the bottom of the mail composition window to use your message extension"::: -Your message extension will be listed. You can invoke it from there and use it just as you would while composing a message in Teams. +Your message extension is listed. You can invoke it from there and use it just as you would while composing a message in Teams. ### Outlook -> [!IMPORTANT] -> Refer to the latest updates on [Microsoft Teams - Microsoft 365 Developer Blog](https://devblogs.microsoft.com/microsoft365dev/) to check if Outlook on Windows desktop support for Teams personal apps is available to your test tenant. - To preview your app running in Outlook on Windows desktop: -1. Launch Outlook logged in with credentials for your test tenant. 1. Click on **New Email**. -1. Open the **More apps** flyout menu on the top ribbon. +1. Launch Outlook logged in with credentials for your test tenant. +1. Select **New Email**. +1. Open the **More Apps** flyout menu on the top ribbon. -Your message extension will be listed. You can invoke it from there and use it just as you would while composing a message in Teams. + :::image type="content" source="images/outlook-desktop-compose-more-apps.png" alt-text="Click on 'More Apps' on the composition window ribbon to use your message extension"::: -## Next steps +Your message extension is listed, it opens an adjacent pane to display search results. -Outlook-enabled Teams message extensions are in preview and not supported for production use. Here's how to distribute your Outlook-enabled message extension to preview audiences for testing purposes. +## Troubleshooting -### Single-tenant distribution + While your updated message extension will continue to run in Teams with full [feature support for message extensions](/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions), there are limitations in this early preview of the Outlook-enabled experience to be aware of: -Outlook- and Office-enabled personal tabs can be distributed to a preview audience across a test (or production) tenant in one of three ways: +* Message extensions in Outlook are limited to the mail [*compose* context](/microsoftteams/platform/resources/schema/manifest-schema#composeextensions). Even if your Teams message extension includes `commandBox` as a *context* in its manifest, the current preview is limited to the mail composition (`compose`) option. Invoking a message extension from the global Outlook *Search* box isn't supported. +* [Action-based message extension](/microsoftteams/platform/messaging-extensions/how-to/action-commands/define-action-command?tabs=AS) command aren't supported in Outlook. If your app has both search- and action-based commands, it will surface in Outlook but the action menu won't be available. +* Insertion of more than five [Adaptive Cards](/microsoftteams/platform/task-modules-and-cards/cards/design-effective-cards?tabs=design) in an email isn't supported; Adaptive Cards v1.4 and later aren't supported. +* [Card actions](/microsoftteams/platform/task-modules-and-cards/cards/cards-actions?tabs=json) of type `messageBack`, `imBack`, `invoke`, and `signin` aren't supported for inserted cards. Support is limited to `openURL`: on click, the user will be redirected to the specified URL in a new tab. -#### Teams client +Use the [Microsoft Teams developer community channels](/microsoftteams/platform/feedback) to report issues and provide feedback. -From the *Apps* menu, select *Manage your apps* > **Submit an app to your org**. This requires approval from your IT admin. +### Debugging -#### Microsoft Teams Admin Center +As you test your message extension, you can identify the source (originating from Teams versus Outlook) of bot requests by the [channelId](https://github.com/Microsoft/botframework-sdk/blob/main/specs/botframework-activity/botframework-activity.md#channel-id) of the [Activity](https://github.com/Microsoft/botframework-sdk/blob/main/specs/botframework-activity/botframework-activity.md) object. When a user performs a query, your service receives a standard Bot Framework `Activity` object. One of the properties in the Activity object is `channelId`, which will have the value of `msteams` or `outlook`, depending from where the bot request originates. For more information, see [Search based message extensions SDK](/microsoftteams/platform/resources/messaging-extension-v3/search-extensions). -As a Teams admin, you can upload and pre-install the app package for your organization's tenant from [Teams admin](https://admin.teams.microsoft.com/). See [Upload your custom apps in the Microsoft Teams admin center](/MicrosoftTeams/upload-custom-apps) for details. +## Code sample -#### Microsoft Admin Center +| **Sample Name** | **Description** | **Node.js** | +||--|--| +| NPM Search Connector | Use Teams Toolkit to build a message extension app. Works in Teams, Outlook. | [View](https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/NPM-search-connector-M365) | -As a global admin, you can upload and pre-install the app package from [Microsoft admin](https://admin.microsoft.com/). See [Test and deploy Microsoft 365 Apps by partners in the Integrated apps portal](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps) for details. +## Next step -### Multitenant distribution +Publish your app to be discoverable in Teams, Outlook, and Office: -Distribution to Microsoft AppSource is not yet supported during this early developer preview of Outlook-enabled Teams message extensions. +> [!div class="nextstepaction"] +> [Publish Teams apps for Outlook and Office](publish.md) |
| platform | Extend M365 Teams Personal Tab | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/extend-m365-teams-personal-tab.md | Title: Extend a Teams personal tab app across Microsoft 365 description: Extend a Teams personal tab app across Microsoft 365 Previously updated : 02/11/2022 Last updated : 05/24/2022 -+ ms.localizationpriority: medium # Extend a Teams personal tab across Microsoft 365 -> [!NOTE] -> *Extending a Teams personal tab across Microsoft 365* is currently available only in [public developer preview](../resources/dev-preview/developer-preview-intro.md). Features included in preview may not be complete, and may undergo changes before becoming available in the public release. They are provided for testing and exploration purposes only. They should not be used in production applications. - Personal tabs provide a great way to enhance the Microsoft Teams experience. Using personal tabs, you can provide a user access to their application right within Teams, without the user having to leave the experience or sign in again. With this preview, personal tabs can light up within other Microsoft 365 applications. This tutorial demonstrates the process of taking an existing Teams personal tab and updating it to run in both Outlook desktop and web experiences, and also Office on the web (office.com). -Updating your personal app to run in Outlook and Office Home involves these steps: +Updating your personal app to run in Outlook and Office involves these steps: > [!div class="checklist"] > Updating your personal app to run in Outlook and Office Home involves these step > * Update your TeamsJS SDK references > * Amend your Content Security Policy headers > * Update your Microsoft Azure Active Directory (Azure AD) App Registration for Single Sign On (SSO)+> * Sideload your updated app in Teams -Testing your app will require the following steps: --> [!div class="checklist"] -> -> * Enroll your Microsoft 365 tenant in *Office 365 Targeted Releases* -> * Configure your account to access preview versions of Outlook and Office apps -> * Sideload your updated app into Teams --After these steps, your app should appear in the preview versions of Outlook and Office apps. +The rest of this guide walks you through these steps and show you how to preview your personal tab in other Microsoft 365 applications. ## Prerequisites To complete this tutorial, you'll need: ## Prepare your personal tab for the upgrade -If you have an existing personal tab app, make a copy or a branch of your production project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID). +If you have an existing personal tab app, make a copy or a branch of your production project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID, for testing). ++If you'd like to use sample code to complete this tutorial, follow the setup steps in the [Todo List Sample](https://github.com/OfficeDev/TeamsFx-Samples/tree/main/todo-list-with-Azure-backend) to build a personal tab app using the Teams Toolkit extension for Visual Studio Code, then return to this article to update it for Microsoft 365. -If you'd like to use sample code to complete this tutorial, follow the setup steps in [Getting Started with Todo List Sample](https://github.com/OfficeDev/TeamsFx-Samples/tree/main/todo-list-with-Azure-backend) to build a personal tab app using the Teams Toolkit extension for Visual Studio Code. Or, you can start with the same [Todo List Sample updated for TeamsJS SDK v2 Preview](https://github.com/OfficeDev/TeamsFx-Samples/tree/main/todo-list-with-Azure-backend-M365) and proceed to [Preview your personal tab in other Microsoft 365 experiences](#preview-your-personal-tab-in-other-microsoft-365-experiences). The updated sample is also available within Teams Toolkit extension: *Development* > *View samples* > **Todo List (Works in Teams, Outlook and Office)**. +Alternately, you can use a basic Single Sign-On *hello world* app already enabled Microsoft 365 in the following quickstart section and then skip to [Sideload your app in Teams](#sideload-your-app-in-teams) . +### Quickstart ++To start with a [personal tab](https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/todo-list-with-Azure-backend-M365) that's already enabled to run in Outlook and Office, use Teams Toolkit extension for Visual Studio Code. ++1. From Visual Studio Code, open the command palette (`Ctrl+Shift+P`), type `Teams: Create a new Teams app`. +1. Select **SSO enabled personal tab**. ++ :::image type="content" source="images/toolkit-tab-sample.png" alt-text="Todo List sample (Works in Teams, Outlook and Office) in Teams Toolkit"::: ++1. Select a location on your local machine for the workspace folder. +1. Open the command palette (`Ctrl+Shift+P`) and type `Teams: Provision in the cloud` to create the required app resources (App Service plan, Storage account, Function App, Managed Identity) in your Azure account. +1. Open the command palette (`Ctrl+Shift+P`) and type `Teams: Deploy to the cloud` to deploy the sample code to the provisioned resources in Azure and start the app. ++From here, you can skip ahead to [Sideload your app in Teams](#sideload-your-app-in-teams) and preview your app in Outlook and Office. (The app manifest and TeamsJS API calls have already been updated for Microsoft 365.) ## Update the app manifest -You'll need to use the [Teams developer preview manifest](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview) schema and the `Microsoft 365 DevPreview` manifest version to enable your Teams personal tab to run in Office and Outlook. +You'll need to use the [Teams developer manifest](../resources/schem) schema version `1.13` to enable your Teams personal tab to run in Outlook and Office. -You can either use Teams Toolkit to update your app manifest, or apply the changes manually: +You have two options for updating your app manifest: # [Teams Toolkit](#tab/manifest-teams-toolkit) -1. Open the *Command palette*: `Ctrl+Shift+P` -1. Run the `Teams: Upgrade Teams manifest to support Outlook and Office apps` command and select your app manifest file. Changes will be made in place. +1. Open the command palette: `Ctrl+Shift+P`. +1. Run the `Teams: Upgrade Teams manifest` command and select your app manifest file. Changes will be made in place. # [Manual steps](#tab/manifest-manual) Open your Teams app manifest and update the `$schema` and `manifestVersion` with ```json {- "$schema" : "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json", - "manifestVersion" : "m365DevPreview" + "$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json", + "manifestVersion" : "1.13" } ``` -If you used Teams Toolkit to create your personal app, you can also use it to validate the changes to your manifest file and identify any errors. Open the command palette `Ctrl+Shift+P` and find **Teams: Validate manifest file** or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code). -+If you used Teams Toolkit to create your personal app, you can also use it to validate the changes to your manifest file and identify any errors. Open the command palette (`Ctrl+Shift+P`) and find **Teams: Validate manifest file**. ## Update SDK references -To run in Outlook and Office, your app will need to depend on the npm package `@microsoft/teams-js@2.0.0-beta.1` (or a later *beta* version). While code with downlevel versions of `@microsoft/teams-js` is supported in Outlook and Office, deprecation warnings will be logged, and support for downlevel versions of `@microsoft/teams-js` in Outlook and Office will eventually cease. +To run in Outlook and Office, your app will need to reference the npm package `@microsoft/teams-js@2.0.0` (or higher). While code with downlevel versions is supported in Outlook and Office, deprecation warnings are logged, and support for downlevel versions of TeamsJS in Outlook and Office will eventually cease. -You can use Teams Toolkit to help automate some of the code changes to adopt the next version of `@microsoft/teams-js`, but if you would like to do the steps manually, see [Microsoft Teams JavaScript client SDK Preview](using-teams-client-sdk-preview.md) for details. +You can use Teams Toolkit to help identify and automate the required code changes to upgrade from 1.x TeamsJS versions to TeamsJS version 2.0.0. Alternately, you can perform the same steps manually; refer to [Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md#whats-new-in-teamsjs-version-20) for details. -1. Open the *Command palette*: `Ctrl+Shift+P` -1. Run the command `Teams: Upgrade Teams JS SDK references to support Outlook and Office apps` +1. Open the *Command palette*: `Ctrl+Shift+P`. +1. Run the command `Teams: Upgrade Teams JS SDK and code references`. -Upon completion, the utility will have updated your `package.json` file with the TeamsJS SDK Preview (`@microsoft/teams-js@2.0.0-beta.1` or later) dependency, and your `*.js/.ts` and `*.jsx/.tsx` files will be updated with: +Upon completion, your *package.json* file will reference `@microsoft/teams-js@2.0.0` (or higher) and your `*.js/.ts` and `*.jsx/.tsx` files will be updated with: > [!div class="checklist"]-> -> * `package.json` references to TeamsJS SDK Preview -> * Import statements for TeamsJS SDK Preview -> * [Function, Enum, and Interface calls](using-teams-client-sdk-preview.md#apis-organized-into-capabilities) to TeamsJS SDK Preview -> * `TODO` comment reminders to review areas that might be impacted by [Context](using-teams-client-sdk-preview.md#updates-to-the-context-interface) interface changes -> * `TODO` comment reminders to ensure [conversion to promises functions from callback style functions](using-teams-client-sdk-preview.md#callbacks-converted-to-promises) has gone well at every call site the tool found +> * Import statements for teams-js@2.0.0 +> * [Function, Enum, and Interface calls](../tabs/how-to/using-teams-client-sdk.md#whats-new-in-teamsjs-version-20) for teams-js@2.0.0 +> * `TODO` comment reminders flagging areas that might be impacted by [Context](../tabs/how-to/using-teams-client-sdk.md#updates-to-the-context-interface) interface changes +> * `TODO` comment reminders to [convert callback functions to promises](../tabs/how-to/using-teams-client-sdk.md#callbacks-converted-to-promises) > [!IMPORTANT]-> Code inside *.html* files is not supported by the upgrade tooling and will require manual changes. --> [!NOTE] -> If you wish to manually update your code, see [Microsoft Teams JavaScript client SDK Preview](using-teams-client-sdk-preview.md) to learn about the required changes. +> Code inside *.html* files is not supported by the upgrade tooling and require manual changes. ## Configure Content Security Policy headers -[Just as in Microsoft Teams](/microsoftteams/platform/tabs/what-are-tabs), tab applications are hosted within ([iframe elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)) in Office and Outlook web clients. +As in Microsoft Teams, tab applications are hosted within [iframe elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) in Office and Outlook web clients. -If your app makes use of [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (CSP) headers, make sure you are allowing all of the following [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) in your CSP headers: +If your app makes use of [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (CSP) headers, make sure you allow all the following [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) in your CSP headers: |Microsoft 365 host| frame-ancestor permission| |--|--| If your app makes use of [Content Security Policy](https://developer.mozilla.org ## Update Azure AD app registration for SSO -Azure Active Directory Single-sign on (SSO) for personal tabs works the same way in Office and Outlook [as it does in Teams](/microsoftteams/platform/tabs/how-to/authentication/auth-aad-sso), however you will need to add several client application identifiers to the Azure AD app registration of your tab app in your tenant's *App registrations* portal. +[Azure Active Directory (AD) Single-sign on (SSO)](../tabs/how-to/authentication/auth-aad-sso.md) for personal tabs works the same way in Office and Outlook as it does in Teams. However you'll need to add several client application identifiers to the Azure AD app registration of your tab app in your tenant's *App registrations* portal. 1. Sign in to [Microsoft Azure portal](https://portal.azure.com) with your sandbox tenant account. 1. Open the **App registrations** blade. 1. Select the name of your personal tab application to open its app registration. 1. Select **Expose an API** (under *Manage*). + :::image type="content" source="images/azure-app-registration-clients.png" alt-text="Authorize client Ids from the *App registrations* blade on Azure portal"::: -In the **Authorized client applications** section, ensure all of the following `Client Id` values are added: +1. In the **Authorized client applications** section, ensure all of the following `Client Id` values are added: -|Microsoft 365 client application | Client ID | -|--|--| -|Teams desktop, mobile |1fec8e78-bce4-4aaf-ab1b-5451cc387264 | -|Teams web |5e3ce6c0-2b1f-4285-8d4b-75ee78787346 | -|Office.com |4765445b-32c6-49b0-83e6-1d93765276ca| -|Office desktop | 0ec893e0-5785-4de6-99da-4ed124e5296c | -|Outlook desktop | d3590ed6-52b3-4102-aeff-aad2292ab01c | -|Outlook Web Access | 00000002-0000-0ff1-ce00-000000000000 | -|Outlook Web Access | bc59ab01-8403-45c6-8796-ac3ef710b3e3 | + |Microsoft 365 client application | Client ID | + |--|--| + |Teams desktop, mobile |1fec8e78-bce4-4aaf-ab1b-5451cc387264 | + |Teams web |5e3ce6c0-2b1f-4285-8d4b-75ee78787346 | + |Office.com |4765445b-32c6-49b0-83e6-1d93765276ca| + |Office desktop | 0ec893e0-5785-4de6-99da-4ed124e5296c | + |Outlook desktop | d3590ed6-52b3-4102-aeff-aad2292ab01c | + |Outlook Web Access | 00000002-0000-0ff1-ce00-000000000000 | + |Outlook Web Access | bc59ab01-8403-45c6-8796-ac3ef710b3e3 | ## Sideload your app in Teams -The final step is to sideload your updated personal tab ([app package](/microsoftteams/platform/concepts/build-and-test/apps-package)) in Microsoft Teams. Once completed, your app will be available to run in Office and Outlook, in addition to Teams. +The final step to running your app in Office and Outlook is to sideload your updated personal tab [app package](..//concepts/build-and-test/apps-package.md) in Microsoft Teams. -1. Package your Teams application (manifest and app [icons](/microsoftteams/platform/resources/schema/manifest-schema#icons)) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the **Zip Teams metadata package** option in the *Deployment* menu of Teams Toolkit or in the Command Palette `Ctrl+Shift+P` of Visual Studio Code: +1. Package your Teams application ([manifest](../resources/schem) and [app icons](/microsoftteams/platform/resources/schema/manifest-schema#icons)) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the **Zip Teams metadata package** option in the **Deployment** menu of Teams Toolkit. :::image type="content" source="images/toolkit-zip-teams-metadata-package.png" alt-text="'Zip Teams metadata package' option in Teams Toolkit extension for Visual Studio Code"::: -1. Log in to Teams with your sandbox tenant account, and ensure that you are on the Public Developer Preview. You can verify that you're on the Preview in the Teams client by clicking on the ellipsis (**...**) menu by your user profile and opening **About** to check that the *Developer preview* option is toggled on. +1. Sign in to Teams with your sandbox tenant account, and toggle into *Developer Preview* mode. Select the ellipsis (**...**) menu by your user profile, then select: **About** > **Developer preview**. - :::image type="content" source="images/teams-dev-preview.png" alt-text="From Teams ellipses menu, open 'About' and verify 'Developer Preview' option is checked"::: + :::image type="content" source="images/teams-dev-preview.png" alt-text="From Teams ellipses menu, open 'About', and select 'Developer Preview' option"::: -1. Open the *Apps* pane, and click **Upload a custom app** and then **Upload for me or my teams**. +1. Select **Apps** to open the **Manage your apps** pane. Then select **Publish an app**. - :::image type="content" source="images/teams-upload-custom-app.png" alt-text="'Upload a custom app' button in the Teams 'Apps' pane"::: + :::image type="content" source="images/teams-manage-your-apps.png" alt-text="Open the 'Manage your apps' pane and select 'Publish an app'"::: -1. Select your app package and click *Open*. +1. Choose **Upload a custom app** option and select your app package. -Once sideloaded through Teams, your personal tab will be available in Outlook and Office. Be sure to sign in with the same credentials you used to sideload your app in Teams. + :::image type="content" source="images/teams-upload-custom-app.png" alt-text="'Upload a custom app' option in Teams"::: -You can pin the app for quick access, or you can find your app in the ellipses (**...**) flyout among recent applications in the sidebar on the left. +After it's sideloaded to Teams, your personal tab is available in Outlook and Office. Be sure to sign in with the same credentials you used to sign in to Teams to sideload your app. -> [!NOTE] -> Pinning an app in Teams will not pin it as an app in Office.com or Outlook. +You can pin the app for quick access, or you can find your app in the ellipses (**...**) flyout among recent applications in the sidebar on the left. Pinning an app in Teams don't pin it as an app in Office or Outlook. ## Preview your personal tab in other Microsoft 365 experiences -When you upgrade your Teams personal tab and sideload it in Teams, it runs in Outlook on Windows, on the web, Office on Windows and on the web (office.com). Here's how to preview it from those Microsoft 365 experiences. +Here's how to preview your app running in Office and Outlook, web and Windows desktop clients. ++> [!NOTE] +> Uninstalling your app from Teams also removes it from the **More Apps** catalogs in Outlook and Office. If you're using the Teams Toolkit sample app provided above. ### Outlook on Windows To view your app running in Outlook on Windows desktop: 1. Launch Outlook and sign in using your dev tenant account.-1. Click on the ellipses (**...**) on the side bar. Your sideloaded app title will appear among your installed apps. -1. Click on your app icon to launch your app in Outlook. +1. On the side bar, select **More Apps**. Your sideloaded app title appears among your installed apps. +1. Select your app icon to launch your app in Outlook. + :::image type="content" source="images/outlook-desktop-more-apps.png" alt-text="Click on the ellipses ('More apps') option on the side bar of Outlook desktop client to see your installed personal tabs"::: ### Outlook on the web To view your app in Outlook on the web: 1. Navigate to [Outlook on the web](https://outlook.office.com) and sign in using your dev tenant account.-1. Click on the ellipses (**...**) on the side bar. Your sideloaded app title will appear among your installed apps. -1. Click on your app icon to launch and preview your app running in Outlook on the web. +1. Select the ellipses (**...**) on the side bar. Your sideloaded app title appears among your installed apps. +1. Select your app icon to launch and preview your app running in Outlook on the web. + :::image type="content" source="images/outlook-web-more-apps.png" alt-text="Click on the ellipses ('More apps') option on the side bar of outlook.com to see your installed personal tabs"::: ### Office on Windows To view your app running in Office on Windows desktop: 1. Launch Office and sign in using your dev tenant account.-1. Click on the ellipses (**...**) on the side bar. Your sideloaded app title will appear among your installed apps. -1. Click on your app icon to launch your app in Office. +1. Select the ellipses (**...**) on the side bar. Your sideloaded app title appears among your installed apps. +1. Select your app icon to launch your app in Office. + :::image type="content" source="images/office-desktop-more-apps.png" alt-text="Click on the ellipses ('More apps') option on the side bar of Office desktop client to see your installed personal tabs"::: ### Office on the web To preview your app running in Office on the web: -1. Log into office.com with test tenant credentials. -1. Click on the ellipses (**...**) on the side bar. Your sideloaded app title will appear among your installed apps. -1. Click on your app icon to launch your app in Office on the web. +1. Log into **office.com** with test tenant credentials. +1. Select the **Apps** icon on the side bar. Your sideloaded app title appears among your installed apps. +1. Select your app icon to launch your app in Office on the web. + :::image type="content" source="images/office-web-more-apps.png" alt-text="Click on the 'More apps' option on the side bar of office.com to see your installed personal tabs"::: -## Next steps +## Troubleshooting -Outlook- and Office-enabled personal tabs are in preview and are not supported for production use. Here's how to distribute your personal tab app to preview audiences for testing purposes. +Currently, a subset of Teams application types and capabilities are supported in Outlook and Office clients. This support expands over time. -### Single-tenant distribution +Refer to [Microsoft 365 support](../tabs/how-to/using-teams-client-sdk.md#microsoft-365-support-running-teams-apps-in-office-and-outlook) to check host support for various TeamsJS capabilities. -Outlook- and Office-enabled personal tabs can be distributed to a preview audience across a test (or production) tenant in one of three ways: +For an overall summary of Microsoft 365 host and platform support for Teams apps, see [Extend Teams apps across Microsoft 365](overview.md). -#### Teams client +You can check for host support of a given capability at runtime by calling the `isSupported()` function on that capability (namespace), and adjusting app behavior as appropriate. This allows your app to light up UI and functionality in hosts that support it, and provide a graceful fallback experience in hosts that don't. For more information, see [Differentiate your app experience](../tabs/how-to/using-teams-client-sdk.md#differentiate-your-app-experience). -From the *Apps* menu, select *Manage your apps* > **Submit an app to your org**. This requires approval from your IT admin. +Use the [Microsoft Teams developer community channels](/microsoftteams/platform/feedback) to report issues and provide feedback. -#### Microsoft Teams Admin Center +### Debugging -As a Teams admin, you can upload and pre-install the app package for your organization's tenant from [Teams admin](https://admin.teams.microsoft.com/). See [Upload your custom apps in the Microsoft Teams admin center](/MicrosoftTeams/upload-custom-apps) for details. +From Teams Toolkit, you can Debug (`F5`) your tab application running in Office and Outlook, in addition to Teams. -#### Microsoft Admin Center -As a global admin, you can upload and pre-install the app package from [Microsoft admin](https://admin.microsoft.com/). See [Test and deploy Microsoft 365 Apps by partners in the Integrated apps portal](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps) for details. +Upon first run of local debug to Office or Outlook, you'll be prompted to sign in to your Microsoft 365 tenant account and install a self-signed test certificate. You'll also be prompted to manually install Teams. Select **Install in Teams** to open a browser window and manually install your app. Then click on **Continue** to proceed to debug your app in Office/Outlook. +++Provide feedback and report any issues with the Teams Toolkit debugging experience at [Microsoft Teams Framework (TeamsFx)](https://github.com/OfficeDev/TeamsFx/issues). ++## Next step ++Publish your app to be discoverable in Teams, Outlook, and Office: ++> [!div class="nextstepaction"] +> [Publish Teams apps for Outlook and Office](publish.md) -### Multitenant distribution +## Code sample -Distribution to Microsoft AppSource is not supported during this early developer preview of Outlook- and Office-enabled Teams personal tabs. +| **Sample Name** | **Description** | **Node.js** | +||--|--| +| Todo List | Editable todo list with SSO built with React and Azure Functions. Works only in Teams (use this sample app to try the upgrade process described in this tutorial). | [View](https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/todo-list-with-Azure-backend) | +| Todo List (Microsoft 365) | Editable todo list with SSO built with React and Azure Functions. Works in Teams, Outlook, Office. | [View](https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/todo-list-with-Azure-backend-M365)| +| Image Editor (Microsoft 365) | Create, edit, open, and save images using Microsoft Graph API. Works in Teams, Outlook, Office. | [View](https://github.com/OfficeDev/m365-extensibility-image-editor) | |
| platform | Overview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/overview.md | Title: Extend Teams apps across Microsoft 365 (preview) description: Extend your Teams app experiences to other high-usage areas of Microsoft 365 Previously updated : 02/11/2022 Last updated : 05/24/2022 ms.localizationpriority: medium # Extend Teams apps across Microsoft 365 -> [!NOTE] -> This early developer preview is intended to provide Teams developers with existing applications the chance to try the new functionality and [provide feedback](/microsoftteams/platform/feedback) on this expansion of the Teams developer platform into other high-usage areas of the Microsoft 365 ecosystem. +With the latest releases of [Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md) (version 2.0.0), [Teams App manifest](../resources/schem), you can build and update Teams apps to run in other high-usage Microsoft 365 products and publish them to the Microsoft commercial marketplace ([Microsoft AppSource](https://appsource.microsoft.com/)). ++Extending your Teams app across Microsoft 365 provides a streamlined way to deliver cross-platform apps to an expanded user audience: from a single codebase, you can create app experiences tailored for Teams, Outlook, and Office environments. End users won't have to leave the context of their work to use your app, and administrators benefit from a consolidated management and deployment workflow. -You can test your Teams apps running in Microsoft Office and Outlook by updating your code to use the new [Microsoft Teams JavaScript client SDK v2 Preview](using-teams-client-sdk-preview.md) and Microsoft Teams [Developer preview manifest](../resources/schem). +The Teams app platform continues to evolve and expand holistically into the Microsoft 365 ecosystem. Here's the current support of Teams app platform elements across Microsoft 365 (Teams, Outlook, and Office as application hosts): -With this preview, you can: +| | App manifest element | Teams support |Outlook* support | Office* support | Notes | +|--|--|--|--|--|--| +| [**Tabs**](../tabs/what-are-tabs.md) (personal scope) |`staticTabs` | Web, Desktop, Mobile | Web (Targeted Release), Desktop (Beta Channel) | Web (Targeted Release)| Channel and group scope not yet supported for Microsoft 365. See [notes](../tabs/how-to/using-teams-client-sdk.md#microsoft-365-support-running-teams-apps-in-office-and-outlook). +| [**Message extensions**](../messaging-extensions/what-are-messaging-extensions.md) (search-based)| `composeExtensions` | Web, Desktop, Mobile| Web (Targeted Release), Desktop (Beta Channel)| |Action-based not yet supported for Microsoft 365. See [notes](extend-m365-teams-message-extension.md#preview-your-message-extension-in-outlook). | +| [**Graph connectors**](/microsoftsearch/connectors-overview)| `graphConnector` | Web, Desktop, Mobile| Web, Desktop | Web| See [notes](#graph-connectors) +| [**Office Add-ins**](/office/dev/add-ins/develop/json-manifest-overview) (preview) | `extensions` | | Web, Desktop | | Only available in [devPreview](../resources/schem) manifest version. See [notes](#office-add-ins-preview).| -- Extend existing Teams [personal tabs](/microsoftteams/platform/tabs/how-to/create-personal-tab) to Outlook for desktop and on the web, and also Office on the web (office.com).-- Extend existing Teams [search-based message extensions](/microsoftteams/platform/messaging-extensions/how-to/search-commands/define-search-command) to Outlook for desktop and on the web.+\* The [Microsoft 365 Targeted release](/microsoft-365/admin/manage/release-options-in-office-365) option and [Microsoft 365 Apps update channel](/deployoffice/change-update-channels) enrollment require admin opt-in for the entire organization or selected users. -For feedback and issues, continue using the relevant [Microsoft Teams developer community channels](/microsoftteams/platform/feedback). +For guidance about the Teams app manifest and SDK versioning guidance, as well as further details about current Teams platform capability support across Microsoft 365, see the [Teams JavaScript client SDK overview](../tabs/how-to/using-teams-client-sdk.md). -## Teams personal tabs in Office and Outlook +> [!NOTE] +> We welcome your feedback and issue reporting as you expand Teams apps to run across the Microsoft 365 ecosystem! Please use the regular [Microsoft Teams developer community channels](/microsoftteams/platform/feedback) to send feedback. -With this preview, you can extend a Teams personal tab application to run in both Outlook on Windows desktop and the web, and also Office on the web. +## Personal tabs and messaging extensions in Outlook and Office -After sideloading to Teams, your personal tab appears as one of your installed apps in Outlook and Office. +Reach your users where they are, right in the context of their work by extending your web app as a Teams personal tab application that also runs in both Outlook and Office. :::image type="content" source="images/outlook-office-teams-personal-tab.png" alt-text="Personal tab running in Outlook, Office, and Teams"::: -## Teams message extensions in Outlook +You can also extend your search-based Teams message extensions to Outlook on the web and Windows desktop, enabling your customers to search and share results through the compose message area of Outlook, in addition to Microsoft Teams clients. + -With this preview, you can extend your search-based Teams message extensions to Outlook on the web and Windows desktop, enabling customers to search and share results through the compose message area of Outlook, in addition to Microsoft Teams clients. +Building your app with the latest [Teams app manifest](../resources/schem) provides you with a consolidated development process. By enabling you to deliver a streamlined deployment, installation, and admin experience for your customers, you can expand the potential reach and usage of your app. -After sideloading to Teams, your message extension appears as one of your installed apps within the Outlook compose message area. +## Use Teams app manifest across Microsoft 365 +With an aim toward simplifying and streamlining the Microsoft 365 developer ecosystem, we're continuing to expand the Teams app manifest into other areas of Microsoft 365 with the following. ++### Graph connectors ++With Microsoft Graph connectors, your organization can index third-party data so that it appears as Microsoft Search results, expanding the types of searchable content sources in your Teams apps. +For more information, see [Microsoft Graph connectors overview for Microsoft Search](/microsoftsearch/connectors-overview). ++To get started with graph connectors in Teams apps, check out the [Teams Toolkit Graph connectors sample](https://aka.ms/teamsfx-graph-connector-sample) and [Microsoft Teams Developer preview manifest schema](../resources/schem) reference. ++### Office Add-ins (preview) ++You can now define and deploy Office Add-ins in the [developer preview version](../resources/schem) of the Microsoft Teams app manifest. Currently this preview is limited to Outlook Add-ins running on subscription Office for Windows. ++For more information, see [Teams manifest for Office Add-ins (preview)](/office/dev/add-ins/develop/json-manifest-overview). ++## Microsoft AppSource submission ++Join the growing number of production Teams apps in the [Microsoft AppSource](https://appsource.microsoft.com/) store with expanded support for Outlook and Office preview (Targeted Release) audiences. The app [submission process for Teams apps enabled for Outlook and Office](../concepts/deploy-and-publish/appsource/publish.md) is the same as for traditional Teams apps; the only difference is you'll use Teams app manifest [version 1.13](../tabs/how-to/using-teams-client-sdk.md) in your app package, which introduces support for Teams apps that run across Microsoft 365. ++Once published as a Microsoft 365-enabled Teams app, your app will be discoverable as an installable app from the Outlook and Office app stores, in addition to the Teams store. When running in Outlook and Office, your app uses the same permissions granted in Teams. Teams admins can [Manage access to Teams apps across Microsoft 365](/MicrosoftTeams/manage-third-party-teams-apps) for users in their organization. ++For more information, see [Publish Teams apps for Microsoft 365](publish.md). -## Next steps +## Next step -Set up your dev environment for extending Teams apps across Microsoft 365: +Set up your dev environment to build Teams apps for Microsoft 365: > [!div class="nextstepaction"] > [Install prerequisites](prerequisites.md) |
| platform | Prerequisites | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/prerequisites.md | Title: Set up your dev environment for extending Teams apps across Microsoft 365 description: Here are the prerequisites for extending your Teams apps across Microsoft 365 Previously updated : 02/11/2022 Last updated : 05/24/2022+ ms.localizationpriority: high # Set up your dev environment for extending Teams apps across Microsoft 365 -> [!NOTE] -> Extend teams app across Microsoft 365 is currently available only in [public developer preview](~/resources/dev-preview/developer-preview-intro.md). - The development environment for extending Teams apps across Microsoft 365 is similar to Microsoft Teams development. This article discusses specific configurations required to run preview builds of Microsoft Teams and Microsoft Office applications in order to preview Teams apps running in Outlook and Office. To set up your development environment: To set up your development environment: > > * [Get Microsoft 365 Developer (Sandbox) Tenant and enable sideloading](#prepare-a-developer-tenant-for-testing) > * [Enroll your Microsoft 365 tenant in *Office 365 Targeted Releases*](#enroll-your-developer-tenant-for-office-365-targeted-releases)-> * [Configure your account to access preview versions of Outlook and Office](#install-office-apps-in-your-test-environment) +> * [Install Beta Channel builds of Microsoft 365 Apps in your test environment](#install-office-apps-in-your-test-environment) > * [Switch to the Developer Preview version of Teams](#switch-to-the-developer-preview-version-of-teams)-> * [*Optional*] [Install Teams Toolkit extension for Microsoft Visual Studio Code](#install-visual-studio-code-and-teams-toolkit-preview-extension) +> * [*Optional*] [Install Teams Toolkit extension for Microsoft Visual Studio Code](#install-visual-studio-code-and-teams-toolkit-extension) ## Prepare a Developer Tenant for testing You need a Microsoft 365 developer subscription sandbox tenant to set up your dev environment. If you don't already have one, create a [sandbox tenant](/office/developer-program/microsoft-365-developer-program-get-started) or get a test tenant through your organization. -After you have a tenant, you need to enable sideloading for your tenant, see [enable sideloading](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-turn-on-custom-app-uploading). To verify if sideloading is enabled, sign in to Teams, select **Apps** and then check for **Upload a custom app** option. +You'll also need to enable sideloading for your tenant: ++1. Sign in to Microsoft 365 admin center (https://admin.microsoft.com) with your test tenant credentials and select **Teams** from the side panel to open the *Microsoft Teams admin center*. +1. Select: Teams apps > Manage apps > **Org-wide app settings**. +1. Under **Custom apps**, toggle on the option *Interaction with custom apps*. + :::image type="content" source="images/teams-admin-enable-sideloading.png" alt-text="Enable sideloading for custom apps from the Teams admin center"::: ## Enroll your developer tenant for Office 365 Targeted releases -> [!IMPORTANT] -> Refer to the latest updates on [Microsoft Teams - Microsoft 365 Developer Blog](https://devblogs.microsoft.com/microsoft365dev/) to check if Outlook.com and Office.com support for Teams apps is available to your test tenant. +> [!Important] +> It can take up to five days after creating a [Microsoft 365 developer sandbox tenant](/office/developer-program/microsoft-365-developer-program-get-started) and enrolling in [Office 365 Targeted releases](#enroll-your-developer-tenant-for-office-365-targeted-releases) for sideloaded Teams apps to appear in Outlook and Office. To enroll your test tenant for Office 365 targeted releases: For more information on Office 365 release options, see [Set up the Standard or ## Install Office apps in your test environment -> [!IMPORTANT] -> Refer to the latest updates on [Microsoft Teams - Microsoft 365 Developer Blog](https://devblogs.microsoft.com/microsoft365dev/) to check if Outlook for Windows desktop support for Teams message extensions is available to your test tenant. - You can preview Teams apps running in Outlook on Windows desktop by using a recent *Beta Channel build*. Check if you have to [Change the Microsoft 365 Apps update channel](/deployoffice/change-update-channels?WT.mc_id=M365-MVP-5002016) for your test tenant to install an Office 365 Beta Channel build. To install Office 365 Beta Channel applications in your test environment: To install Office 365 Beta Channel applications in your test environment: 1. Open Command Prompt and navigate to the local folder path. 1. Run `setup.exe /configure configuration-Office365-x86.xml` (or use the **x64.xml* file, depending on your setup). 1. Open Outlook (desktop client) and set up the mail account using your test tenant credentials.-1. Open **File** > **Office Account** > **About Outlook**. - If the build number is **14416** or higher and the channel is *Beta Channel*, you're running Microsoft 365 beta Channel build. -1. In the top-right corner, turn on the **Coming Soon** toggle. -- :::image type="content" source="images/outlook-coming-soon.png" alt-text="'Coming Soon' toggle option in Outlook"::: +1. Open **File** > **Office Account** > **About Outlook** to confirm you're running a Microsoft 365 *Beta Channel* build of Outlook. -> [!NOTE] -> You may need to close Outlook and restart your computer for the *Coming Soon* button to appear. + :::image type="content" source="images/outlook-about-beta-channel.png" alt-text="Go to 'About Outlook' from your Office Account to verify you are running a Beta Channel build."::: -You can verify test tenant support for your tenant account: +1. Verify that *Microsoft Edge WebView2 Runtime* is installed. Open Windows **Start** > **Apps & features**, and search for **webview**: -* For Teams personal tabs running on office.com, outlook.com, and Outlook for Windows desktop, sign in with your test tenant credentials and check for ellipses (**...**) option on the left sidebar of Office or Outlook. + :::image type="content" source="images/windows-addremove-webview2.png" alt-text="Search for 'webview' under 'Apps and features' in your Windows Settings"::: - :::image type="content" source="images/outlook-desktop-ellipses.png" alt-text="Ellipses ('...') option on the left sidebar of Outlook"::: --* For message extensions in outlook.com and Outlook for Windows, check for **More Apps** option at the bottom of the Outlook compose message pane. -- :::image type="content" source="images/outlook-web-compose-more-apps.png" alt-text="'More apps' option in the Outlook compose message pane"::: --> [!NOTE] -> If you're opted in to Beta Channel releases but you don't see these ellipses options, it's likely that preview feature support is in the process of rolling out to your tenant. For the latest updates, see [Microsoft Teams Developer Blog](https://devblogs.microsoft.com/microsoft365dev/). + If it's not listed, install [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) to your test environment. ## Switch to the Developer Preview version of Teams Ensure that you switch to the [Public Developer Preview](../resources/dev-previe :::image type="content" source="images/teams-dev-preview.png" alt-text="Public developer preview option in Teams"::: -## Install Visual Studio Code and Teams Toolkit Preview extension +## Install Visual Studio Code and Teams Toolkit extension Optionally, you can use [Visual Studio Code](https://code.visualstudio.com/) to extend Teams apps into Office and Outlook. The extension [Teams Toolkit for Visual Studio Code](https://aka.ms/teams-toolkit) (`v2.10.0` or later) provides commands that can help modify your existing Teams code to be compatible with Outlook and Office. For more information, see [enable Teams personal tab for Office and Outlook](extend-m365-teams-personal-tab.md). -## Next steps +## Next step ++Create or update a Teams app to run across Microsoft 365: -* [Enable a Teams personal tab for Office and Outlook](extend-m365-teams-personal-tab.md) -* [Enable a Teams message extension for Outlook](extend-m365-teams-message-extension.md) +> [!div class="nextstepaction"] +> [Enable a Teams personal tab for Office and Outlook](extend-m365-teams-personal-tab.md) +> [!div class="nextstepaction"] +> [Enable a Teams message extension for Outlook](extend-m365-teams-message-extension.md) |
| platform | Publish | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/publish.md | + + Title: Publish Teams apps for Microsoft 365 +description: Make your Microsoft 365-enabled Teams apps discoverable to users in Teams, Outlook, and Office Last updated : 05/24/2022+++ms.localizationpriority: medium ++# Publish Teams apps for Microsoft 365 ++Microsoft 365-enabled Teams apps are supported for production use in Microsoft Teams. You can distribute these apps to preview audiences who use the *Targeted Release* versions of outlook.com and office.com, and the *Beta Channel* build of Outlook for Windows desktop. Distribution options and processes for Microsoft 365-enabled Teams apps are the same as for traditional Teams apps. ++After it's published, your app will be discoverable as an installable app from the Outlook and Office app stores, in addition to the Teams store. Your app uses the permissions defined in Teams across Outlook and Office. Teams admins can [manage access to Teams apps across Microsoft 365](/MicrosoftTeams/manage-third-party-teams-apps) for users in their organization. +++## Single-tenant distribution ++Outlook-enabled message extensions can be distributed to test and production tenants in several ways: ++### Teams client ++From the **Apps** menu, select **Manage your apps** > **Publish an app** > **Submit an app to your org**. This requires approval from your IT admin. ++### Teams Developer Portal ++Use the [Teams Developer Portal](https://dev.teams.microsoft.com/) to upload and publish an app to your organization. This requires approval from your IT admin. For more information, see [Manage your apps with the Developer Portal for Microsoft Teams](../concepts/build-and-test/teams-developer-portal.md). ++### Microsoft Teams Admin Center ++As a Teams admin, you can upload and pre-install the app package for your organization's tenant from [Teams admin center](https://admin.teams.microsoft.com/). For more information, see [Upload your custom apps in the Microsoft Teams admin center](/MicrosoftTeams/upload-custom-apps). ++### Microsoft Admin Center ++As a global admin, you can upload and pre-install the app package from [Microsoft admin](https://admin.microsoft.com/). For more information, see [Test and deploy Microsoft 365 Apps by partners in the Integrated apps portal](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps). ++## Multitenant distribution ++The [Microsoft AppSource](https://appsource.microsoft.com/) (Microsoft commercial marketplace) submission process for Teams apps enabled for Outlook and Office is same as traditional Teams apps. The only difference is you'll need to use Teams app manifest [version 1.13](../tabs/how-to/using-teams-client-sdk.md) in your app package, which introduces support for Teams apps that run across Microsoft 365. ++> [!TIP] +> Use Teams Developer Portal to [validate your app package](https://dev.teams.microsoft.com/validation) to resolve any errors or warnings before submitting to the Teams store (via [Microsoft Partner Network](https://partner.microsoft.com/)). ++To get started, see [Distribute your Microsoft Teams app](../concepts/deploy-and-publish/apps-publish-overview.md). |
| platform | Using Teams Client Sdk Preview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/using-teams-client-sdk-preview.md | - Title: Microsoft Teams JavaScript client SDK v2 Preview -description: Understand the changes coming with Microsoft Teams JavaScript client SDK v2 Preview Previously updated : 11/15/2021----# Microsoft Teams JavaScript client SDK v2 Preview --With the [Microsoft Teams JavaScript client SDK v2 Preview](/javascript/api/overview/msteams-client?view=msteams-client-js-beta&preserve-view=true), the existing Teams SDK (`@microsoft/teams-js`, or simply `TeamsJS`) has been refactored to enable Teams developers the ability to [extend Teams apps to run in Outlook and Office](overview.md). From a functional perspective, the TeamsJS SDK v2 Preview (`@microsoft/teams-js@next`) is a superset of the current TeamsJS SDK, it supports existing Teams app functionality while adding the ability to host Teams apps in Outlook and Office. --There are two significant changes in the TeamsJS SDK v2 Preview that your code will need to account for in order to run in other Microsoft 365 applications: --* [**Callback functions now return Promise objects.**](#callbacks-converted-to-promises) All existing functions with a callback parameter have been modernized to return a JavaScript [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object for improved handling of asynchronous operations and code readability. --* [**APIs are now organized into *capabilities*.**](#apis-organized-into-capabilities) You can think of capabilities as logical groupings of APIs that provide similar functionality, such as `authentication`, `calendar`, `mail`, `monetization`, `meeting`, and `sharing`. -- You can use the [Teams Toolkit extension](https://aka.ms/teams-toolkit) for Microsoft Visual Studio Code to simplify the update process for your Teams app, as described in the following section. --> [!NOTE] -> Enabling an existing Teams app to run in Outlook and Office requires both: -> -> 1. Dependency on the `@microsoft/teams-js@2.0.0-beta.1` or later, and -> 2. Modifying existing application code according to the required changes described in this document. -> -> If you reference `@microsoft/teams-js@2.0.0-beta.1` (or later) from an existing Teams app, you will see deprecation warnings if your code calls APIs that have changed. An API translation layer (mapping current SDK to preview SDK API calls) is provided to enable existing Teams apps to continue working in Teams until they are able to update code to work with the TeamsJS SDK v2 Preview. After you update your code with the changes outlined in this article, your personal tab will also run in Outlook and Office. --## Updating to the Teams client SDK v2 Preview --The easiest way to update your Teams app to use the TeamsJS SDK v2 Preview is to use the [Teams Toolkit extension](https://aka.ms/teams-toolkit) for Visual Studio Code. This section will walk you through the steps to do that. If you prefer to manually update your code, see the [Callbacks converted to promises](#callbacks-converted-to-promises) and [APIs organized into capabilities](#apis-organized-into-capabilities) sections for more details on required API changes. --### 1. Install the latest Teams Toolkit Visual Studio Code extension --In the *Visual Studio Code Extensions Marketplace*, search for **Teams Toolkit** and install version `2.10.0` or later. The toolkit provides two commands to assist the process: --1. A command to update your manifest schema -1. A command to update your SDK references and call sites --Following are the two key updates you'll need to run a Teams personal tab app in other Microsoft 365 applications: -`` --### 2. Updating the manifest --# [Teams Toolkit](#tab/manifest-teams-toolkit) --1. Open the *Command palette*: `Ctrl+Shift+P` -1. Run **Teams: Upgrade Teams manifest to support Outlook and Office apps** command and select your app manifest file. Changes will be made in place. --# [Manual steps](#tab/manifest-manual) --Open your Teams app manifest and update the `$schema` and `manifestVersion` with the following values: --```json -{ - "$schema" : "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json", - "manifestVersion" : "m365DevPreview" -} -``` ----If you used Teams Toolkit to create your personal app, you can also use it to validate the changes to your manifest file and identify any errors. Open the command palette `Ctrl+Shift+P` and find **Teams: Validate manifest file** or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code). ---### 2. Update SDK references --To run in Outlook and Office, your app will need to depend on the [npm package](https://www.npmjs.com/package/@microsoft/teams-js/v/2.0.0-beta.1) `@microsoft/teams-js@2.0.0-beta.1` (or a later *beta* version). To perform these steps manually, and for more information on the API changes, see the following sections on [Callbacks converted to promises](#callbacks-converted-to-promises) and [APIs organized into capabilities](#apis-organized-into-capabilities). --1. Ensure you have [Teams Toolkit](https://aka.ms/teams-toolkit) `v2.10.0` or later -1. Open the *Command palette*: `Ctrl+Shift+P` -1. Run the command `Teams: Upgrade Teams JS SDK references to support Outlook and Office apps` --After completion, the utility will have updated your `package.json` file with the TeamsJS SDK v2 Preview (`@microsoft/teams-js@2.0.0-beta.1` or later) dependency, and your `*.js/.ts` and `*.jsx/.tsx` files will be updated with: --> [!div class="checklist"] -> -> * `package.json` references to TeamsJS SDK v2 Preview -> * Import statements for TeamsJS SDK v2 Preview -> * [Function, Enum, and Interface calls](#apis-organized-into-capabilities) to TeamsJS SDK v2 Preview -> * `TODO` comment reminders to review areas that might be impacted by [Context](#updates-to-the-context-interface) interface changes -> * `TODO` comment reminders to ensure [conversion to promises functions from callback style functions](#callbacks-converted-to-promises) has gone well at every call site the tool found --> [!IMPORTANT] -> Code inside html files is not supported by the upgrade tooling and will require manual changes. --## Callbacks converted to promises --Teams APIs that previously took a callback parameter have been updated to return a JavaScript [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object. These include the following APIs: --```js -app.getContext, app.initialize, appInstallDialog.openAppInstallDialog, authentication.authenticate, authentication.getAuthToken, authentication.getUser, authentication.registerAuthenticationHandlers was removed to support using Promises, calendar.openCalendarItem, calendar.composeMeeting, call.startCall, core.executeDeepLink, location.getLocation, location.showLocation, mail.openMailItem, mail.composeMail, media.captureImage, media.getMedia, media.selectMedia, media.viewImages, media.scanBarCode, meeting.getAppContentStageSharingCapabilities, meeting.getAuthenticationTokenForAnonymousUser, meeting.getIncomingClientAudioState, meeting.getLiveStreamState, meeting.getMeetingDetails, meeting.requestStartLiveStreaming, meeting.requestStopLiveStreaming, meeting.shareAppContentToStage, meeting.stopSharingAppContentToStage, meeting.toggleIncomingClientAudio, meeting.getAppContentStageSharingState, pages.backStack.navigateBack, pages.navigateCrossDomain, pages.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.config.setConfig, pages.config.getConfig, people.selectPeople, ChildAppWindow.postMessage, ParentAppWindow.postMessage -``` --You'll need to update the way your code calls any of these APIs to use Promises. For example, if your code is calling a Teams API like this: --# [JavaScript](#tab/javascript) --This code: --```js -import microsoftTeams from "@microsoft/teams-js"; --microsoftTeams.getContext((context) => { /* ... */ }); -``` --Needs to be updated to: --```js -import { app, Context } from "@microsoft/teams-js"; --app.getContext().then((context) => { - /*...*/ -}); -``` --...or the equivalent `async/await` pattern: --```js -import { app, Context } from "@microsoft/teams-js"; --async function example() { - const context = await app.getContext(); - /*...*/ -} -``` --# [TypeScript](#tab/typescript) --This code: --```TypeScript -import * as microsoftTeams from "@microsoft/teams-js"; --microsoftTeams.getContext((context: microsoftTeams.Context) => { - /* ... */ -}); -``` --Needs to be updated to: --```TypeScript -import { app, Context } from "@microsoft/teams-js"; --app.getContext().then((context: Context) => { - /*...*/ -}); -``` --...or the equivalent `async/await` pattern: --```TypeScript -import { app, Context } from "@microsoft/teams-js"; --async function example() { - const context: Context = await app.getContext(); - /*...*/ -} -``` ----> [!TIP] -> When you update your code for the TeamsJS SDK v2 Preview using [Teams Toolkit](#updating-to-the-teams-client-sdk-v2-preview), the required updates are flagged for you with `TODO` comments in your client code. --## APIs organized into capabilities --A *capability* is a logical grouping of APIs that provide similar functionality. You can think of Microsoft Teams, Outlook, and Office, as hosts. A host supports a given capability if it supports all the APIs defined within that capability. A host cannot partially implement a capability. Capabilities can be feature- or content-based, such as *dialog* or *authentication*. There are also capabilities for application types, such as *tabs/pages* or *bots*, and other groupings. --In the TeamsJS SDK v2 Preview, APIs are defined as functions in a JavaScript namespace whose name matches their required capability. If an app is running in a host that supports the dialog capability, then the app can safely call APIs such as `dialog.open` (in addition to other dialog-related APIs defined in the namespace). Meanwhile, if an app attempts to call an API that's not supported in that host, the API will throw an exception. --### Differentiate your app experience --You can check for host support of a given capability at runtime by calling the `isSupported()` function on that capability (namespace). It will return `true` if it is supported and `false` if not, and you can adjust app behavior as appropriate. This allows your app to light up UI and functionality in hosts that support it, while continuing to run for hosts that don't. --The name of the host your app is running in is exposed as a *hostName* property on the Context interface (`app.Context.app.host.name`), which can be queried at runtime by calling `getContext`. It is also available as a `{hostName}` [URL placeholder value](../tabs/how-to/access-teams-context.md#get-context-by-inserting-url-placeholder-values). Best practice is to use the *hostName* mechanism sparingly: --* **Don't** assume certain functionality is or isn't available in a host based on the *hostName* property value. Instead, check for capability support (`isSupported`). -* **Don't** use *hostName* to gate API calls. Instead, check for capability support (`isSupported`). -* **Do** use *hostName* to differentiate the theme of your application based on the host its running in. For example, you can use Microsoft Teams purple as the main accent color when running in Teams, and Outlook blue when running in Outlook. -* **Do** use *hostName* to differentiate messages shown to the user based on which host it's running in. For example, show *Manage your tasks in Office* when running in Office on the web, and *Manage your tasks in Teams* when running in Microsoft Teams. --### Namespaces --The TeamsJS SDK v2 Preview organizes APIs into *capabilities* by way of namespaces. Several new namespaces of particular importance are *app*, *pages*, *dialog*, and *teamsCore*. --#### *app* namespace --The `app` namespace contains top-level APIs required for overall app usage, across Microsoft Teams, Office, and Outlook. All the APIs from various other TeamsJS namespaces have been moved to the `app` namespace in TeamsJS SDK v2 Preview: --| Original namespace `global (window)` | New namespace `app` | -| - | - | -| `initialize` | `app.initialize` | -| `getContext` | `app.getContext` | -| `registerOnThemeChangeHandler` | `app.registerOnThemeChangeHandler` | --| Original namespace `appInitialization` | New namespace `app` | -| - | - | -| `appInitialization.notifyAppLoaded` | `app.notifyAppLoaded` | -| `appInitialization.notifySuccess` | `app.notifySuccess` | -| `appInitialization.notifyFailure` | `app.notifyFailure` | -| `appInitialization.notifyExpectedFailure` | `app.notifyExpectedFailure` | -| `appInitialization.FailedReason` enum | `app.FailedReason` | -| `appInitialization.ExpectedFailureReason` enum | `app.ExpectedFailureReason` | -| `appInitialization.IFailedRequest` enum | `app.IFailedRequest` | -| `appInitialization.IExpectedFailureRequest` enum | `app.IExpectedFailureRequest` | --#### *core* namespace --The `core` namespace includes functionality for deep links. --| Original namespace `publicAPIs` | New namespace `core` | -| - | - | -| `shareDeepLink` | `core.shareDeepLink` | -| `executeDeepLink` | `core.executeDeepLink` | --#### *pages* namespace --The `pages` namespace includes functionality for running and navigating webpages within various Microsoft 365 clients, including Teams, Office, and Outlook. It also includes several sub-capabilities, implemented as sub-namespaces. --| Original namespace `global (window)` | New namespace `pages` | -| - | - | -| `setFrameContext` | `pages.setCurrentFrame` (renamed) | -| `initializeWithFrameContext` | `pages.initializeWithFrameContext` | -| `registerFullScreenHandler` | `pages.registerFullScreenHandler` | -| `navigateCrossDomain` | `pages.navigateCrossDomain` | -| `returnFocus` | `pages.returnFocus` | --##### *pages.tabs* --| Original namespace `global (window)` | New namespace `pages.tabs` | -| - | - | -| `getTabInstances` | `pages.tabs.getTabInstances` | -| `getMruTabInstances` | `pages.tabs.getMruTabInstances` | -| `navigateToTab` | `pages.tabs.navigateToTab` | --| Original namespace `navigation` | New namespace `pages.tabs` | -| - | - | -| `navigation.navigateToTab` | `pages.tabs.navigateToTab` | --##### *pages.config* --| Original namespace `settings` | New namespace `pages.config` | -| - | - | -| `settings.setSettings` | `pages.config.setConfig` (renamed) -| `settings.getSettings` | `pages.config.getConfig` (renamed) -| `settings.setValidityState`| `pages.config.setValidityState` -| `settings.initialize` | `pages.config.initialize` -| `settings.registerOnSaveHandler`| `pages.config.registerOnSaveHandler` -| `settings.registerOnRemoveHandler` | `pages.config.registerOnRemoveHandler` -| `settings.Settings` interface | `pages.config.Config` (renamed) -| `settings.SaveEvent` interface | `pages.config.SaveEvent` (renamed) -| `settings.RemoveEvent` interface | `pages.config.RemoveEvent` (renamed) -| `settings.SaveParameters` interface | `pages.config.SaveParameters` (renamed) -| `settings.SaveEventImpl` interface | `pages.config.SaveEventImpl` (renamed) --| Original namespace `global (window)` | New namespace `pages.config` | -| - | - | -| `registerEnterSettingsHandler` | `pages.config.registerChangeConfigHandler` (renamed) --##### *pages.backStack* --| Original namespace `navigation` | New namespace `pages.backStack` | -| - | - | -| `navigation.navigateBack` | `pages.backStack.navigateBack` --| Original namespace `global (window)` | New namespace `pages.backStack` | -| - | - | -| `registerBackButtonHandler` | `pages.backStack.registerBackButtonHandler` --##### *pages.appButton* --| Original namespace `global (window)` | New namespace `pages.appButton` | -| - | - | -| `registerAppButtonClickHandler` | `pages.appButton.onClick` (renamed) -| `registerAppButtonHoverEnterHandler` | `pages.appButton.onHoverEnter` (renamed) -| `registerAppButtonHoverLeaveEnter` | `pages.appButton.onHoverLeave` (renamed) -| `FrameContext` interface | `pages.appButton.FrameInfo` (renamed)) | --#### *dialog* namespace --The TeamsJS *tasks* namespace has been renamed to *dialog*, and the following APIs have been renamed: --| Original namespace `tasks` | New namespace `dialog` | -| - | - | -| `tasks.startTask` | `dialog.open` (renamed) | -| `tasks.submitTasks` | `dialog.submit` (renamed) | -| `tasks.updateTasks` | `dialog.resize` (renamed) | -| `tasks.TaskModuleDimension` enum | `dialog.DialogDimension` (renamed) | -| `tasks.TaskInfo` interface | `dialog.DialogInfo` (renamed) | --#### *teamsCore* namespace --To generalize the TeamsJS SDK to run other Microsoft 365 hosts such as Office and Outlook, Teams-specific functionality (originally in the *global* namespace) has been moved to a *teamsCore* namespace: --| Original namespace `global (window)` | New namespace `teamsCore` | -| - | - | -| `enablePrintCapability` | `teamsCore.enablePrintCapability` -| `print` | `teamsCore.print` -| `registerOnLoadHandler` | `teamsCore.registerOnLoadHandler` -| `registerBeforeUnloadHandler` | `teamsCore.registerBeforeUnloadHandler` -| `registerFocusEnterHandler` | `teamsCore.registerFocusEnterHandler` --### Updates to the *Context* interface --The `Context` interface has been moved to the `app` namespace and updated to group similar properties for better scalability as it runs in Outlook and Office, in addition to Teams. --A new property `app.Context.app.host.name` has been added to enable personal tabs to differentiate user experience depending on the host application. --You can also visualize the changes by reviewing the [`transformLegacyContextToAppContext`](https://github.com/OfficeDev/microsoft-teams-library-js/blob/2.0-preview/packages/teams-js/src/public/app.ts) function in the TeamsJS SDK v2 Preview source. --| Original name in `Context` interface | New location in `app.Context` | -| - | - | -| `appIconPosition` | `app.Context.app.iconPositionVertical` | -| `appLaunchId`| *NOT IN Teams client SDK v2 Preview* | -| `appSessionId` | `app.Context.app.sessionId`| -| `channelId`| `app.Context.channel.id` | -| `channelName`| `app.Context.channel.displayName`| -| `channelRelativeUrl` | `app.Context.channel.relativeUrl`| -| `channelType`| `app.Context.channel.membershipType` | -| `chatId` | `app.Context.chat.id`| -| `defaultOneNoteSectionId`| `app.Context.channel.defaultOneNoteSectionId`| -| `entityId` | `app.Context.page.id`| -| `frameContext` | `app.Context.page.frameContext`| -| `groupId`| `app.Context.team.groupId` | -| `hostClientType` | `app.Context.app.host.clientType`| -| `hostTeamGroupId`| `app.Context.channel.ownerGroupId` | -| `hostTeamTenantId` | `app.Context.channel.ownerTenantId`| -| `isCallingAllowed` | `app.Context.user.isCallingAllowed`| -| `isFullScreen` | `app.Context.page.isFullScreen`| -| `isMultiWindow`| `app.Context.page.isMultiWindow` | -| `isPSTNCallingAllowed` | `app.Context.user.isPSTNCallingAllowed`| -| `isTeamArchived` | `app.Context.team.isArchived`| -| `locale` | `app.Context.app.locale` | -| `loginHint`| `app.Context.user.loginHint` | -| `meetingId`| `app.Context.meeting.id` | -| `osLocaleInfo` | `app.Context.app.osLocaleInfo` | -| `parentMessageId`| `app.Context.app.parentMessageId`| -| `ringId` | `app.Context.app.host.ringId`| -| `sessionId`| `app.Context.app.host.sessionId` | -| `sourceOrigin` | `app.Context.page.sourceOrigin`| -| `subEntityId`| `app.Context.page.subPageId` | -| `teamId` | `app.Context.team.internalId`| -| `teamSiteDomain` | `app.Context.sharepointSite.domain`| -| `teamSitePath` | `app.Context.sharepointSite.path`| -| `teamSiteUrl`| `app.Context.sharepointSite.url` | -| `teamTemplateId` | `app.Context.team.templateId`| -| `teamType` | `app.Context.team.type`| -| `tenantSKU`| `app.Context.user.tenant.teamsSku` | -| `tid`| `app.Context.user.tenant.id` | -| `upn` | `app.Context.user.userPrincipalName` | -|`userClickTime`| `app.Context.app.userClickTime`| -| `userFileOpenPreference` | `app.Context.app.userFileOpenPreference` | -| `userLicenseType`| `app.Context.user.licenseType` | -| `userObjectId` | `app.Context.user.id`| -| `userTeamRole` | `app.Context.team.userRole`| -| `userDisplayName` | `app.Context.user.displayName` | -| N/A | `app.Context.app.host.name`| --## Next steps --You can also learn more about breaking changes in the [TeamsJS SDK v2 Preview changelog](https://github.com/OfficeDev/microsoft-teams-library-js/blob/2.0-preview/packages/teams-js/CHANGELOG.md) and the [TeamsJS SDK v2 Preview API Reference](/javascript/api/overview/msteams-client?view=msteams-client-js-beta&preserve-view=true). --When you're ready to test your Teams apps running in Outlook and Office, see: --> [!div class="nextstepaction"] -> [Extend your Teams app across Microsoft 365](overview.md) |
| platform | Manifest Schema Dev Preview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/resources/schema/manifest-schema-dev-preview.md | The `https://` URL referencing the JSON Schema for the manifest. **Required** – String -The version of the manifest schema this manifest is using. Use `m365DevPreview` only if you are previewing [Teams apps running in Office and Outlook](../../m365-apps/overview.md). Otherwise, use `devPreview` for all other Teams preview features. +The version of the manifest schema this manifest is using. ## version Specify your Microsoft Azure Active Directory (Azure AD) App ID and Graph inform |`resource`|String|2048 characters|Γ£ö|Resource URL of the app for acquiring auth token for SSO.| |`applicationPermissions`|Array|Maximum 100 items|Γ£ö|Resource permissions for application.| +## graphConnector ++**Optional**ΓÇöobject ++Specify the app's Graph connector configuration. If this is present then [webApplicationInfo.id](#webapplicationinfo) must also be specified. ++|Name| Type| Maximum size | Required | Description| +|||||| +|`notificationUrl`|string|2048 characters|Γ£ö|The url where Graph-connector notifications for the application should be sent.| ++## showLoadingIndicator ++**Optional**ΓÇöBoolean ++Indicates whether or not to show the loading indicator when an app or tab is loading. Default is **false**. +> [!NOTE] +> If you select`showLoadingIndicator` as true in your app manifest, to load the page correctly, modify the content pages of your tabs and task modules as described in [Show a native loading indicator](../../tabs/how-to/create-tab-pages/content-page.md#show-a-native-loading-indicator) document. ++## isFullScreen ++ **Optional**ΓÇöBoolean ++Indicate where a personal app is rendered with or without a tab header bar. Default is **false**. ++> [!NOTE] +> `isFullScreen` works only for apps published to your organization. ++## activities ++**Optional**ΓÇöobject ++Define the properties your app uses to post a user activity feed. ++|Name| Type| Maximum size | Required | Description| +|||||| +|`activityTypes`|array of Objects|128 items| | Provide the types of activities that your app can post to a users activity feed.| ++### activities.activityTypes ++|Name| Type| Maximum size | Required | Description| +|||||| +|`type`|string|32 characters|Γ£ö|The notification type. *See below*.| +|`description`|string|128 characters|Γ£ö|A brief description of the notification. *See below*.| +|`templateText`|string|128 characters|Γ£ö|Ex: "{actor} created task {taskId} for you"| ++```json +{ + "activities":{ + "activityTypes":[ + { + "type":"taskCreated", + "description":"Task Created Activity", + "templateText":"{actor} created task {taskId} for you" + }, + { + "type":"teamMention", + "description":"Team Mention Activity", + "templateText":"{actor} mentioned team" + }, + { + "type":"channelMention", + "description":"Channel Mention Activity", + "templateText":"{actor} mentioned channel" + }, + { + "type":"userMention", + "description":"Personal Mention Activity", + "templateText":"{actor} mentioned user" + }, + { + "type":"calendarForward", + "description":"Forwarding a Calendar Event", + "templateText":"{actor} sent user an invite on behalf of {eventOwner}" + }, + { + "type":"calendarForward", + "description":"Forwarding a Calendar Event", + "templateText":"{actor} sent user an invite on behalf of {eventOwner}" + }, + { + "type":"creatorTaskCreated", + "description":"Created Task Created", + "templateText":"The Creator created task {taskId} for you" + } + ] + } +} +``` ++*** + ## configurableProperties **Optional** - array Delegated permissions allow the app to access data on behalf of the signed-in us ||| |`InAppPurchase.Allow.User`|Allows the app to show the user marketplace offers and complete the user's purchases within the app, on behalf of the signed-in user.| +* **Resource-specific permissions for Teams live share** ++ |Name| Description | + | -- | -- | + |`LiveShareSession.ReadWrite.Chat`|<! need info >| + |`LiveShareSession.ReadWrite.Channel`|<! need info >| + |`MeetingStage.Write.Chat`|<! need info >| + |`OnlineMeetingIncomingAudio.Detect.Chat`|<! need info >| + ## See also * [Understand the Microsoft Teams app structure](~/concepts/design/app-structure.md) |
| platform | Manifest Schema | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/resources/schema/manifest-schema.md | Title: Manifest schema reference description: Describes the manifest schema for Microsoft Teams - ms.localizationpriority: high keywords: teams manifest schema # Reference: Manifest schema for Microsoft Teams -The Teams manifest describes how the app integrates into the Microsoft Teams product. Your manifest must conform to the schema hosted at [`https://developer.microsoft.com/json-schemas/teams/v1.12/MicrosoftTeams.schema.json`]( https://developer.microsoft.com/json-schemas/teams/v1.12/MicrosoftTeams.schema.json). Previous versions 1.0, 1.1,..., and 1.12 are also supported (using "v1.x" in the URL). +The Microsoft Teams app manifest describes how your app integrates into the Microsoft Teams product. Your app manifest must conform to the schema hosted at [`https://developer.microsoft.com/json-schemas/teams/v1.12/MicrosoftTeams.schema.json`]( https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json). Previous versions 1.0, 1.1,...,1.12 and the current 1.13 version (see note below) are also supported (using "v1.x" in the URL). For more information on the changes made in each version, see [manifest change log](https://github.com/OfficeDev/microsoft-teams-app-schema/releases). +> [!Important] +> Version `1.13` of the Microsoft Teams app manifest schema enables support for [extending Teams apps to Outlook and Office](../../m365-apps/overview.md). For Teams-only apps, use version `1.12` (or earlier). The 1.12 and 1.13 schemas are otherwise the same. Refer to [Teams JavaScript client SDK](../../m365-apps/overview.md) overview for further guidance. + The following schema sample shows all extensibility options: ## Sample full manifest The https:// URL referencing the JSON Schema for the manifest. **Required**ΓÇöstring -The version of manifest schema this manifest is using. +The version of the manifest schema that this manifest is using. Use `1.13` to enable Teams app support in Outlook and Office; use `1.12` (or earlier) for Teams-only apps. ## version Provide your Azure Active Directory App ID and Microsoft Graph information to he |`id`|string|36 characters|Γ£ö|Azure AD application ID of the app. This ID must be a GUID.| |`resource`|string|2048 characters|Γ£ö|Resource URL of app for acquiring auth token for SSO. </br> **NOTE:** If you are not using SSO, ensure that you enter a dummy string value in this field to your app manifest, for example, https://notapplicable to avoid an error response. | +## graphConnector ++**Optional**ΓÇöobject ++Specify the app's Graph connector configuration. If this is present then [webApplicationInfo.id](#webapplicationinfo) must also be specified. ++|Name| Type| Maximum size | Required | Description| +|||||| +|`notificationUrl`|string|2048 characters|Γ£ö|The url where Graph-connector notifications for the application should be sent.| + ## showLoadingIndicator **Optional**ΓÇöBoolean Indicates if or not to show the loading indicator when an app or tab is loading. **Optional**ΓÇöBoolean -Indicate where a personal app is rendered with or without a tab header bar. Default is **false**. +Indicates if a personal app is rendered without a tab header bar (signifying full screen mode). Default is **false**. > [!NOTE] > `isFullScreen` works only for apps published to your organization. |
| platform | Tab Requirements | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/tabs/how-to/tab-requirements.md | Ensure that you adhere to the following prerequisites while building your Teams | | Install | For using... | | | | | | **Required** | | |-| | [Node.js](https://nodejs.org/en/download/) | Back-end JavaScript runtime environment. Use the latest v14 LTS release.| +| | [Node.js](https://nodejs.org/en/download/) | Back-end JavaScript runtime environment. Use the latest v16 LTS release.| | | [Microsoft Edge](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | | | [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. | | | [Visual Studio 2019](https://visualstudio.com/download), **ASP.NET and web development**, or **.NET Core cross-platform development** workload | .NET. You can install the free community edition of Visual Studio 2019. | |
| platform | Using Teams Client Sdk | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/tabs/how-to/using-teams-client-sdk.md | Title: Building tabs and other hosted experiences with the JavaScript client SDK + Title: Building tabs and other hosted experiences with the Microsoft Teams JavaScript client SDK -description: Overview of the Microsoft Teams JavaScript client SDK, which can help you build Teams app experiences hosted in an <iframe>. It includes basic functions, authentication namespace, and settings namespace. +description: Overview of the Microsoft Teams JavaScript client SDK, which can help you build app experiences hosted in an <iframe> in Teams, Office, and Outlook. ms.localizationpriority: high-keywords: teams tabs group channel configurable static SDK JavaScript personal +keywords: teams tabs group channel configurable static SDK JavaScript personal m365 # Building tabs and other hosted experiences with the Microsoft Teams JavaScript client SDK -The Microsoft Teams JavaScript client SDK can help you create hosted experiences in Teams, which means displaying your app content in an iframe. --The SDK is helpful for developing apps with any of the following Teams capabilities: +The Microsoft Teams JavaScript client SDK can help you create hosted experiences in Teams, Office, and Outlook, where your app content is hosted in an [iframe](https://developer.mozilla.org/docs/Web/HTML/Element/iframe). The SDK is helpful for developing apps with the following Teams capabilities: * [Tabs](../../tabs/what-are-tabs.md)-* [Task modules](../../task-modules-and-cards/what-are-task-modules.md) +* [Dialogs (Task modules)](../../task-modules-and-cards/what-are-task-modules.md) ++Starting with version `2.0.0`, the existing Teams client SDK (`@microsoft/teams-js`, or simply `TeamsJS`) has been refactored to enable [Teams apps to run in Outlook and Office](/m365-apps/overview.md), in addition to Microsoft Teams. From a functional perspective, the latest version of TeamsJS supports all existing (v.1.x.x) Teams app functionality while adding the optional ability to host Teams apps in Outlook and Office. ++Here's the current versioning guidance for various app scenarios: ++| |[TeamsJS](/javascript/api/overview/msteams-client) version | [App manifest](../../resources/schem) version| Next steps| +|||--|| +|**Teams apps extended to Office/Outlook**| TeamsJS v.2.0 or later | **1.13** or later | [Extend a Teams app to run across Microsoft 365](../../m365-apps/extend-m365-teams-personal-tab.md) or [Create a new Microsoft 365 app](../../m365-apps/extend-m365-teams-personal-tab.md#quickstart) | +|**Existing Teams-only apps**| Update to TeamsJS v.2.0 when possible (v.1.12 is still supported*) | 1.12 | [Understand TeamsJS backwards compatibility](#backwards-compatibility) and [Update to TeamsJS v.2.0](#updating-to-the-teams-client-sdk-v200) | +|**New Teams-only apps**| TeamsJS v.2.0 or later | 1.12 | [Create a new Teams app using Teams Toolkit](../../toolkit/create-new-project.md) | ++**Best practice is to use the latest TeamsJS (v.2.0 or later) whenever possible, in order to benefit from the latest improvements and new feature support (even for Teams-only apps). TeamsJS v.1.12 will continue to be supported, but no new features or improvements will be added.* ++The remainder of this article will walk you through the structure and latest updates to the Teams JavaScript client SDK. ++### Microsoft 365 support (running Teams apps in Office and Outlook) ++TeamsJS v.2.0 introduces the ability for certain types of Teams apps to run across the Microsoft 365 ecosystem. Currently, other Microsoft 365 application hosts (including Office and Outlook) for Teams apps support a subset of the application types and capabilities you can build for the Teams platform. This support will expand over time. For a summary of host support for Teams apps, see [Extend Teams apps across Microsoft 365](../../m365-apps/overview.md). ++The following table lists Teams tabs and dialogs (task modules) capabilities (public namespaces) with expanded support to run in other Microsoft 365 hosts. ++> [!TIP] +> Check for host support of a given capability at runtime by calling the `isSupported()` function on that capability (namespace). ++|Capability | Host support | Notes | +|--|--|-| +| app | Teams, Outlook, Office | Namespace representing app initialization and lifecycle. | +| appInitialization| | Deprecated. Replaced by `app` namespace. | +| appInstallDialog | Teams|| +| authentication | Teams, Outlook, Office | | +| calendar | Teams, Outlook || +| call | Teams|| +| chat |Teams|| +| dialog | Teams, Outlook, Office | Namespace representing dialogs (formerly named *task modules*. See notes on [Dialogs](#dialogs). | +| location |Teams| See notes on [App permissions](#app-permissions).| +| mail | Outlook (Windows desktop only)|| +| media |Teams| See notes on [App permissions](#app-permissions).| +| pages | Teams, Outlook, Office | Namespace representing page navigation. See notes on [Deep linking](#deep-linking). | +| people |Teams|| +| settings || Deprecated. Replaced by `pages.config`.| +| sharing | Teams|| +| tasks | | Deprecated. Replaced by `dialog` capability. See notes on [Dialogs](#dialogs).| +| teamsCore | Teams | Namespace containing Teams-specific functionality.| +| video | Teams|| ++#### App permissions ++App capabilities that require the user to grant [device permissions](../../concepts/device-capabilities/device-capabilities-overview.md) (such as *location*) aren't yet supported for apps running outside of Teams. There is currently no way to check app permissions in Settings or your app header when running in Outlook or Office. If a Teams app running in Office or Outlook calls a TeamsJS (or HTML5) API that triggers device permissions, that API will throw an error and fail to display a system dialog asking for user consent. ++Current guidance for now is to modify your code to catch the failure: ++* Check [isSupported()](#differentiate-your-app-experience) on a capability before using it. `media`, `meeting`, and `files` do not yet support *isSupported* calls and do not yet work outside of Teams. +* Catch and handle errors when calling TeamsJS and HTML5 APIs. ++When an API is unsupported or throws an error, add logic to fail gracefully or provide a workaround. For example: ++* Direct the user to your app's website. +* Direct the user to use the app in Teams to complete the flow. +* Notify the user the functionality isn't yet available. ++Additionally, best practice is to ensure your app manifest only specifies the device permissions it's using. ++#### Deep linking ++Prior to TeamsJS version 2.0, all deep linking scenarios were handled using `shareDeepLink` (to generate a link *to* a specific part of your app) and `executeDeepLink` (to navigate to a deeplink *from* or *within* your app). TeamsJS v.2.0 introduces a new API, `navigateToApp`, for navigating to pages (and subpages) within an app in a consistent way across app hosts (Office and Outlook, in addition to Teams). Here's the updated guidance for deep linking scenarios: ++##### Deep links into your app ++Use `pages.shareDeepLink` (known as *shareDeepLink* prior to TeamsJS v.2.0) to generate and display a copyable link for the user to share. When clicked, a user will be prompted to install the app if it's not already installed for the application host (specified in the link path). ++##### Navigation within your app ++Use the new `pages.navigateToApp` API to navigate within your app within the hosting application. ++This API provides the equivalent of navigating to a deep link (as the now deprecated *executeDeepLink* was once used for) without requiring your app to construct a URL or manage different deep link formats for different application hosts. ++##### Deep links out of your app ++For deep links from your app to various areas of its current host, use the strongly typed APIs provided by the TeamsJS SDK. For example, use the *Calendar* capability to open a scheduling dialog or calendar item from your app. ++For deep links from your app to other apps running in the same host, use `pages.navigateToApp`. ++For any other external deep linking scenarios, you can use `app.openLink`, which provides similar functionality to the now deprecated (starting in TeamsJS v.2.0) *executeDeepLink* API. ++#### Dialogs ++Starting with version 2.0 of TeamsJS, the Teams platform concept of [task module](../../task-modules-and-cards/what-are-task-modules.md) has been renamed to *dialog* for better consistency with existing concepts across the Microsoft 365 developer ecosystem. Accordingly, the `tasks` namespace has been deprecated in favor of the new `dialog` namespace. ++This new dialog capability is split into a main capability (`dialog`) for supporting HTML-based dialogs and a subcapability, `dialog.bot`, for bot-based dialog development. ++The dialog capability doesn't yet support [Adaptive card dialogs](../../task-modules-and-cards/task-modules/design-teams-task-modules.md). Adaptive card-based dialogs still need to be invoked using `tasks.startTask()`. ++The `dialog.open` function currently only works for opening HTMl-based dialogs, and it returns a callback function (`PostMessageChannel`) you can use to pass messages (`ChildAppWindow.postMessage`) to the newly opened dialog. `dialog.open` returns a callback (rather than a Promise) because it doesn't require app execution to pause waiting for the dialog to close (thus providing more flexibility for various user interaction patterns). ++## What's new in TeamsJS version 2.0 ++There are two significant changes between TeamsJS 1.x.x versions and v.2.0.0 and later: ++* [**Callback functions now return Promise objects.**](#callbacks-converted-to-promises) Most functions with callback parameters in TeamsJS v.1.12 have been modernized to return a JavaScript [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) object for improved handling of asynchronous operations and code readability. ++* [**APIs are now organized into *capabilities*.**](#apis-organized-into-capabilities) You can think of capabilities as logical groupings of APIs that provide similar functionality, such as `authentication`, `dialog`, `chat`, and `calendar`. Each namespace represents a separate capability. ++> [!TIP] +> You can use the [Teams Toolkit extension](https://aka.ms/teams-toolkit) for Microsoft Visual Studio Code to simplify the [TeamsJS v.2.0 update process](#updating-to-the-teams-client-sdk-v200) for an existing Teams app. ++### Backwards compatibility ++Once you start referencing `@microsoft/teams-js@2.0.0` (or later) from an existing Teams app, you'll see deprecation warnings for any code calling APIs that have changed. ++An API translation layer (mapping v.1 SDK to v.2 SDK API calls) is provided to enable existing Teams apps to continue working in Teams until they're able to update application code to use the TeamsJS v.2 API patterns. ++#### Teams-only apps ++Even if you intend your app to only run in Teams (and not Office and Outlook), best practice is to start referencing the latest TeamsJS (*v.2.0* or later) as soon as convenient, in order to benefit from the latest improvements, new features, and support (even for Teams-only apps). TeamsJS v.1.12 will continue to be supported, but no new features or improvements will be added. ++Once you're able, the next step is to [update existing application code](#2-update-sdk-references) with the changes described in this article. In the meantime, the v.1 to v.2 API translation layer provides backwards compatibility, ensuring your existing Teams app continues to work in TeamsJS version 2.0. ++#### Teams apps running across Microsoft 365 ++Enabling an existing Teams app to run in Outlook and Office requires all of the following: ++1. Dependency on TeamsJS version 2.0 ( `@microsoft/teams-js@2.0`) or later, ++2. [Modifying existing application code](#2-update-sdk-references) according to the required changes described in this article, and ++3. [Updating your app manifest](#3-update-the-manifest-optional) to version 1.13 or later. ++For more info, see [Extend Teams apps across Microsoft 365](../../m365-apps/overview.md). ++### Callbacks converted to promises ++Teams APIs that previously took a callback parameter have been updated to return a JavaScript [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object. These include the following APIs: ++```js +app.getContext, app.initialize, appInstallDialog.openAppInstallDialog, app.openLink, authentication.authenticate, authentication.getAuthToken, authentication.getUser, authentication.registerAuthenticationHandlers was removed to support using Promises, calendar.openCalendarItem, calendar.composeMeeting, call.startCall, chat.getChatMembers, conversations.openConversation, location.getLocation, location.showLocation, mail.openMailItem, mail.composeMail, pages.backStack.navigateBack, pages.navigateCrossDomain, pages.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams +``` ++You'll need to update the way your code calls any of these APIs to use Promises. For example, if your code is calling a Teams API like this: ++# [JavaScript](#tab/javascript) ++This code: ++```js +import microsoftTeams from "@microsoft/teams-js"; ++microsoftTeams.getContext((context) => { /* ... */ }); +``` ++Needs to be updated to: ++```js +import { app, Context } from "@microsoft/teams-js"; ++app.getContext().then((context) => { + /*...*/ +}); +``` ++...or the equivalent `async/await` pattern: ++```js +import { app, Context } from "@microsoft/teams-js"; -For example, the SDK can make your [tab react to theme changes](../../build-your-first-app/build-personal-tab.md#3-update-your-tab-theme) your users make in the Teams client. +async function example() { + const context = await app.getContext(); + /*...*/ +} +``` -## Getting started +# [TypeScript](#tab/typescript) -Do one of the following depending on your development preferences: +This code: -* [Install the SDK with npm or Yarn](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true) -* [Clone the SDK (GitHub)](https://github.com/OfficeDev/microsoft-teams-library-js) +```TypeScript +import * as microsoftTeams from "@microsoft/teams-js"; -## Common SDK functions +microsoftTeams.getContext((context: microsoftTeams.Context) => { + /* ... */ +}); +``` -See the following tables to understand commonly used SDK functions. The [SDK reference documentation](/javascript/api/@microsoft/teams-js/?view=msteams-client-js-latest&preserve-view=true) provides more comprehensive information. +Needs to be updated to: -### Basic functions +```TypeScript +import { app, Context } from "@microsoft/teams-js"; -| Function | Description | Documentation| -| -- | -- | -- | -| `microsoftTeams.initialize()` | Initializes the SDK. This function must be called before any other SDK calls.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-initialize&preserve-view=true)| -|`microsoftTeams.getContext(callback: (context: Context)`| Gets the current state in which the page is running. The callback retrieves the **Context** object.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest&preserve-view=true)<br/>[context obj](/javascript/api/@microsoft/teams-js/@microsoft.teams-js?view=msteams-client-js-latest&preserve-view=true)| -| `microsoftTeams.initializeWithContext({contentUrl: string, websiteUrl: string})` | Initializes the Teams library and sets the tab's [frame context](/javascript/api/@microsoft/teams-js/microsoftteams.framecontext?view=msteams-client-js-latest&preserve-view=true) depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-initializewithframecontext&preserve-view=true)| -| `microsoftTeams.setFrameContext({contentUrl: string, websiteUrl: string})` | Sets the tab's [frame context](/javascript/api/@microsoft/teams-js/microsoftteams.framecontext?view=msteams-client-js-latest&preserve-view=true) depending on the contentUrl and websiteUrl. This ensures the go-to-website/reload functionality operates on the correct URL.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-setframecontext&preserve-view=true)| -| `microsoftTeams.registerFullScreenHandler(handler: (isFullScreen: Boolean)` |The handler that is registered when the user toggles a tab's full-screen/windowed view.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-registerfullscreenhandler&preserve-view=true)<br/>[Boolean](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-registerfullscreenhandler&preserve-view=true)| -|`microsoftTeams.registerChangeSettingsHandler()` |The handler that is registered when the user selects the enabled **Settings** button to reconfigure a tab.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest&preserve-view=true)| -| `microsoftTeams.getTabInstances(callback: (tabInfo: TabInformation),tabInstanceParameters?: TabInstanceParameters,)` |Gets the tabs owned by the app. The callback retrieves the **TabInformation** object. The **TabInstanceParameters** object is an optional parameter.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-gettabinstances&preserve-view=true)<br/>[tabInfo obj](/javascript/api/@microsoft/teams-js/microsoftteams.tabinformation?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.getMruTabInstances(callback: (tabInfo: TabInformation),tabInstanceParameters?: TabInstanceParameters)`|Gets the most recently used tabs for the user. The callback retrieves the **TabInformation** object. The **TabInstanceParameters** object is an optional parameter.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-getmrutabinstances&preserve-view=true)<br/>[tabInfo obj](/javascript/api/@microsoft/teams-js/microsoftteams.tabinformation?view=msteams-client-js-latest&preserve-view=true)<br/>[tabInstance obj](/javascript/api/@microsoft/teams-js/microsoftteams.tabinstanceparameters?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.shareDeepLink(deepLinkParameters: DeepLinkParameters)`|Takes the **DeepLinkParameters** object as input and shares a deep link dialog box that a user can use to navigate to content *within the tab*.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-sharedeeplink&preserve-view=true)<br/>[deepLink obj](/javascript/api/@microsoft/teams-js/microsoftteams.deeplinkparameters?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.executeDeepLink(deepLink: string, onComplete?: (status: Boolean, reason?: string))`|Takes a required **deepLink** as input and navigates user to a URL or triggers a client actionΓÇösuch as opening or installingΓÇöan app *within Teams*.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-executedeeplink&preserve-view=true)| -|`microsoftTeams.navigateToTab(tabInstance: TabInstance, onComplete?: (status: Boolean, reason?: string))`|Takes the **TabInstance** object as input and navigates to a specified tab instance.|[function](/javascript/api/@microsoft/teams-js/microsoftteams?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-navigatetotab&preserve-view=true)<br/>[tabInstance obj](/javascript/api/@microsoft/teams-js/microsoftteams.tabinstance?view=msteams-client-js-latest&preserve-view=true)| +app.getContext().then((context: Context) => { + /*...*/ +}); +``` -### Authentication namespace +...or the equivalent `async/await` pattern: -| Function | Description | Documentation| -| -- | -- | -- | -|`microsoftTeams.authentication.authenticate(authenticateParameters?: AuthenticateParameters)`|Initiates an authentication request that opens a new window with the parameters provided by the caller. Optional input values are defined by the **AuthenticateParameters** object.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.authentication?view=msteams-client-js-latest&preserve-view=true)<br/>[auth obj](/javascript/api/@microsoft/teams-js/microsoftteams.authentication.authenticateparameters?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.authentication.notifySuccess(result?: string, callbackUrl?: string)`|Notifies the frame that initiated the authentication request that the request was successful and closes the authentication window|[function](/javascript/api/@microsoft/teams-js/microsoftteams.authentication?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.authentication.notifyFailure(reason?: string, callbackUrl?: string)`|Notifies the frame that initiated the authentication request that the request failed and closes the authentication window.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.authentication?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.authentication.getAuthToken(authTokenRequest: AuthTokenRequest)`|Send request to issue Azure AD token on behalf of the app. The token can be acquired from the cache, if it has not expired. Otherwise, a request is sent to Azure AD to obtain a new token.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.authentication?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-authentication-getauthtoken&preserve-view=true)| +```TypeScript +import { app, Context } from "@microsoft/teams-js"; ++async function example() { + const context: Context = await app.getContext(); + /*...*/ +} +``` ++++> [!TIP] +> When you use [Teams Toolkit to update to TeamsJS v.2.0](#updating-to-the-teams-client-sdk-v200), the required updates are flagged for you with `TODO` comments in your client code. ++### APIs organized into capabilities ++A *capability* is a logical grouping (via namespace) of APIs that provide similar functionality. You can think of Microsoft Teams, Outlook, and Office, as hosts to your tab app. A host supports a given capability if it supports all the APIs defined within that capability. A host can't partially implement a capability. Capabilities can be feature- or content-based, such as *authentication*, or *dialog*. There are also capabilities for application types such as *pages*, and other groupings. ++Starting with TeamsJS v.2.0, APIs are defined as functions in a JavaScript namespace whose name matches their required capability. For example, if an app is running in a host that supports the *dialog* capability, then the app can safely call APIs such as `dialog.open` (in addition to other dialog-related APIs defined in the namespace). If an app attempts to call an API that's not supported in that host, the API will throw an exception. To verify if the current host running your app supports a given capability, call the [isSupported()](#differentiate-your-app-experience) function of its namespace. ++#### Differentiate your app experience ++You can check for host support of a given capability at runtime by calling the `isSupported()` function on that capability (namespace). It will return `true` if it's supported and `false` if not, and you can adjust app behavior as appropriate. This allows your app to light up UI and functionality in hosts that support it, while continuing to run for hosts that don't. ++The name of the host your app is running in is exposed as a *hostName* property on the Context interface (`app.Context.app.host.name`), which can be queried at runtime by calling `getContext`. It's also available as a `{hostName}` [URL placeholder value](./access-teams-context.md#get-context-by-inserting-url-placeholder-values). Best practice is to use the *hostName* mechanism sparingly: ++* **Don't** assume certain functionality is or isn't available in a host based on the *hostName* property value. Instead, check for capability support (`isSupported`). +* **Don't** use *hostName* to gate API calls. Instead, check for capability support (`isSupported`). +* **Do** use *hostName* to differentiate the theme of your application based on the host it's running in. For example, you can use Microsoft Teams purple as the main accent color when running in Teams, and Outlook blue when running in Outlook. +* **Do** use *hostName* to differentiate messages shown to the user based on which host it's running in. For example, show *Manage your tasks in Office* when running in Office on the web, and *Manage your tasks in Teams* when running in Microsoft Teams. ++#### Namespaces ++Starting with TeamsJS v.2.0, APIs are organized into *capabilities* by way of namespaces. Several new namespaces of particular importance are *app*, *pages*, *dialog*, and *teamsCore*. ++##### *app* namespace ++The `app` namespace contains top-level APIs required for overall app usage, across Microsoft Teams, Office, and Outlook. All the APIs from various other TeamsJS namespaces have been moved to the `app` namespace as of TeamsJS v.2.0: ++| Original namespace `global (window)` | New namespace `app` | +| - | - | +| `executeDeepLink` | `app.openLink` (renamed) | +| `initialize` | `app.initialize` | +| `getContext` | `app.getContext` | +| `registerOnThemeChangeHandler` | `app.registerOnThemeChangeHandler` | ++| Original namespace `appInitialization` | New namespace `app` | +| - | - | +| `appInitialization.notifyAppLoaded` | `app.notifyAppLoaded` | +| `appInitialization.notifySuccess` | `app.notifySuccess` | +| `appInitialization.notifyFailure` | `app.notifyFailure` | +| `appInitialization.notifyExpectedFailure` | `app.notifyExpectedFailure` | +| `appInitialization.FailedReason` enum | `app.FailedReason` | +| `appInitialization.ExpectedFailureReason` enum | `app.ExpectedFailureReason` | +| `appInitialization.IFailedRequest` enum | `app.IFailedRequest` | +| `appInitialization.IExpectedFailureRequest` enum | `app.IExpectedFailureRequest` | ++##### *pages* namespace ++The `pages` namespace includes functionality for running and navigating webpages within various Microsoft 365 hosts, including Teams, Office, and Outlook. It also includes several subcapabilities, implemented as subnamespaces. ++| Original namespace `global (window)` | New namespace `pages` | +| - | - | +| `setFrameContext` | `pages.setCurrentFrame` (renamed) | +| `initializeWithFrameContext` | `pages.initializeWithFrameContext` | +| `registerFocusEnterHandler` | `pages.registerFocusEnterHandler` +| `registerFullScreenHandler` | `pages.registerFullScreenHandler` | +| `navigateCrossDomain` | `pages.navigateCrossDomain` | +| `returnFocus` | `pages.returnFocus` | +| `shareDeepLink` | `pages.shareDeepLink` | ++| Original namespace `settings` | New namespace `pages` | +| - | - | +| `settings.getSettings` | `pages.getConfig` (renamed) ++###### *pages.tabs* ++| Original namespace `global (window)` | New namespace `pages.tabs` | +| - | - | +| `getTabInstances` | `pages.tabs.getTabInstances` | +| `getMruTabInstances` | `pages.tabs.getMruTabInstances` | ++| Original namespace `navigation` | New namespace `pages.tabs` | +| - | - | +| `navigation.navigateToTab` | `pages.tabs.navigateToTab` | ++###### *pages.config* ++| Original namespace `settings` | New namespace `pages.config` | +| - | - | +| `settings.setSettings` | `pages.config.setConfig` (renamed) +| `settings.setValidityState`| `pages.config.setValidityState` +| `settings.initialize` | `pages.config.initialize` +| `settings.registerOnSaveHandler`| `pages.config.registerOnSaveHandler` +| `settings.registerOnRemoveHandler` | `pages.config.registerOnRemoveHandler` +| `settings.Settings` interface | `pages.config.Config` (renamed) +| `settings.SaveEvent` interface | `pages.config.SaveEvent` (renamed) +| `settings.RemoveEvent` interface | `pages.config.RemoveEvent` (renamed) +| `settings.SaveParameters` interface | `pages.config.SaveParameters` (renamed) +| `settings.SaveEventImpl` interface | `pages.config.SaveEventImpl` (renamed) ++| Original namespace `global (window)` | New namespace `pages.config` | +| - | - | +| `registerChangeConfigHandler` | `pages.config.registerChangeConfigHandler` (renamed) ++###### *pages.backStack* ++| Original namespace `navigation` | New namespace `pages.backStack` | +| - | - | +| `navigation.navigateBack` | `pages.backStack.navigateBack` ++| Original namespace `global (window)` | New namespace `pages.backStack` | +| - | - | +| `registerBackButtonHandler` | `pages.backStack.registerBackButtonHandler` ++###### *pages.appButton* ++| Original namespace `global (window)` | New namespace `pages.appButton` | +| - | - | +| `registerAppButtonClickHandler` | `pages.appButton.onClick` (renamed) +| `registerAppButtonHoverEnterHandler` | `pages.appButton.onHoverEnter` (renamed) +| `registerAppButtonHoverLeaveEnter` | `pages.appButton.onHoverLeave` (renamed) +| `FrameContext` interface | `pages.appButton.FrameInfo` (renamed)) | ++##### *dialog* namespace ++The TeamsJS *tasks* namespace has been renamed to *dialog*, and the following APIs have been renamed: ++| Original namespace `tasks` | New namespace `dialog` | +| - | - | +| `tasks.startTask` | `dialog.open` (renamed) | +| `tasks.submitTasks` | `dialog.submit` (renamed) | +| `tasks.updateTasks` | `dialog.update.resize` (renamed) | +| `tasks.TaskModuleDimension` enum | `dialog.DialogDimension` (renamed) | +| `tasks.TaskInfo` interface | `dialog.DialogInfo` (renamed) | ++Additionally, this capability has been split into a main capability (`dialog`) for supporting HTML-based dialogs, and a subcapability for bot-based dialogs, `dialog.bot`. ++##### *teamsCore* namespace ++To generalize the TeamsJS SDK to run other Microsoft 365 hosts such as Office and Outlook, Teams-specific functionality (originally in the *global* namespace) has been moved to a *teamsCore* namespace: ++| Original namespace `global (window)` | New namespace `teamsCore` | +| - | - | +| `enablePrintCapability` | `teamsCore.enablePrintCapability` +| `print` | `teamsCore.print` +| `registerOnLoadHandler` | `teamsCore.registerOnLoadHandler` +| `registerBeforeUnloadHandler` | `teamsCore.registerBeforeUnloadHandler` ++#### Updates to the *Context* interface ++The `Context` interface has been moved to the `app` namespace and updated to group similar properties for better scalability as it runs in Outlook and Office, in addition to Teams. ++A new property `app.Context.app.host.name` has been added to enable tabs to differentiate user experience depending on the host application. ++You can also visualize the changes by reviewing the `transformLegacyContextToAppContext` function in the [TeamsJS v.2.0 source](https://github.com/OfficeDev/microsoft-teams-library-js/blob/main/packages/teams-js/src/public/app.ts) (*app.ts* file). ++| Original name in `Context` interface | New location in `app.Context` | +| - | - | +| `appIconPosition` | `app.Context.app.iconPositionVertical` | +| `appLaunchId`| *NOT IN TeamsJS v.2.0* | +| `appSessionId` | `app.Context.app.sessionId`| +| `channelId`| `app.Context.channel.id` | +| `channelName`| `app.Context.channel.displayName`| +| `channelRelativeUrl` | `app.Context.channel.relativeUrl`| +| `channelType`| `app.Context.channel.membershipType` | +| `chatId` | `app.Context.chat.id`| +| `defaultOneNoteSectionId`| `app.Context.channel.defaultOneNoteSectionId`| +| `entityId` | `app.Context.page.id`| +| `frameContext` | `app.Context.page.frameContext`| +| `groupId`| `app.Context.team.groupId` | +| `hostClientType` | `app.Context.app.host.clientType`| +| `hostTeamGroupId`| `app.Context.channel.ownerGroupId` | +| `hostTeamTenantId` | `app.Context.channel.ownerTenantId`| +| `isCallingAllowed` | `app.Context.user.isCallingAllowed`| +| `isFullScreen` | `app.Context.page.isFullScreen`| +| `isMultiWindow`| `app.Context.page.isMultiWindow` | +| `isPSTNCallingAllowed` | `app.Context.user.isPSTNCallingAllowed`| +| `isTeamArchived` | `app.Context.team.isArchived`| +| `locale` | `app.Context.app.locale` | +| `loginHint`| `app.Context.user.loginHint` | +| `meetingId`| `app.Context.meeting.id` | +| `osLocaleInfo` | `app.Context.app.osLocaleInfo` | +| `parentMessageId`| `app.Context.app.parentMessageId`| +| `ringId` | `app.Context.app.host.ringId`| +| `sessionId`| `app.Context.app.host.sessionId` | +| `sourceOrigin` | `app.Context.page.sourceOrigin`| +| `subEntityId`| `app.Context.page.subPageId` | +| `teamId` | `app.Context.team.internalId`| +| `teamSiteDomain` | `app.Context.sharepointSite.domain`| +| `teamSitePath` | `app.Context.sharepointSite.path`| +| `teamSiteUrl`| `app.Context.sharepointSite.url` | +| `teamTemplateId` | `app.Context.team.templateId`| +| `teamType` | `app.Context.team.type`| +| `tenantSKU`| `app.Context.user.tenant.teamsSku` | +| `tid`| `app.Context.user.tenant.id` | +| `upn` | `app.Context.user.userPrincipalName` | +|`userClickTime`| `app.Context.app.userClickTime`| +| `userFileOpenPreference` | `app.Context.app.userFileOpenPreference` | +| `userLicenseType`| `app.Context.user.licenseType` | +| `userObjectId` | `app.Context.user.id`| +| `userTeamRole` | `app.Context.team.userRole`| +| `userDisplayName` | `app.Context.user.displayName` | +| N/A | `app.Context.app.host.name`| ++## Updating to the Teams client SDK v.2.0.0 ++The easiest way to update your Teams app to use TeamsJS v.2.0 is to use the [Teams Toolkit extension](https://aka.ms/teams-toolkit) for Visual Studio Code. This section will walk you through the steps to do that. If you prefer to manually update your code, see the [Callbacks converted to promises](#callbacks-converted-to-promises) and [APIs organized into capabilities](#apis-organized-into-capabilities) sections for more details on required API changes. ++### 1. Install the latest Teams Toolkit Visual Studio Code extension ++In the *Visual Studio Code Extensions Marketplace*, search for **Teams Toolkit** and install version `2.10.0` or later. ++### 2. Update SDK references ++To run in Outlook and Office, your app will need to depend on the [npm package](https://www.npmjs.com/package/@microsoft/teams-js/v/2.0.0) `@microsoft/teams-js@2.0.0` (or later). To perform these steps manually, and for more information on the API changes, see the following sections on [Callbacks converted to promises](#callbacks-converted-to-promises) and [APIs organized into capabilities](#apis-organized-into-capabilities). ++1. Ensure you have [Teams Toolkit](https://aka.ms/teams-toolkit) `v.2.10.0` or later +1. Open the *Command palette*: `Ctrl+Shift+P` +1. Run the command `Teams: Upgrade Teams JS SDK references to support Outlook and Office apps` ++After completion, the utility will have updated your `package.json` file with the TeamsJS v.2.0 (`@microsoft/teams-js@2.0.0` or later) dependency, and your `*.js/.ts` and `*.jsx/.tsx` files will be updated with: ++> [!div class="checklist"] +> +> * `package.json` references to TeamsJS v.2.0 +> * Import statements for TeamsJS v.2.0 +> * [Function, Enum, and Interface calls](#apis-organized-into-capabilities) to TeamsJS v.2.0 +> * `TODO` comment reminders to review areas that might be impacted by [Context](#updates-to-the-context-interface) interface changes +> * `TODO` comment reminders to [convert callback functions to promises](#callbacks-converted-to-promises) ++> [!IMPORTANT] +> Code inside html files is not supported by the upgrade tooling and will require manual changes. ++### 3. Update the manifest (optional) ++If you're updating a Teams app to run in Office and Outlook, you'll also need to update the app manifest to version 1.13 or later. You can do this easily with Teams Toolkit, or manually. ++# [Teams Toolkit](#tab/manifest-teams-toolkit) ++1. Open the *Command palette*: `Ctrl+Shift+P` +1. Run **Teams: Upgrade Teams manifest to support Outlook and Office apps** command and select your app manifest file. Changes will be made in place. ++# [Manual steps](#tab/manifest-manual) ++Open your Teams app manifest and update the `$schema` and `manifestVersion` with the following values: ++```json +{ + "$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json", + "manifestVersion" : "1.13" +} +``` ++ -### Settings namespace +If you used Teams Toolkit to create your personal app, you can also use it to validate the changes to your manifest file and identify any errors. Open the command palette `Ctrl+Shift+P` and find **Teams: Validate manifest file** or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code). -| Function | Description | Documentation| -| -- | -- | -- | -|`microsoftTeams.settings.setValidityState(validityState: Boolean)`|The initial value is false. Activates the **Save** or **Remove** button when the validity state is true.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.settings.getSettings(callback: (instanceSettings: Settings)`|Gets the settings for the current instance. The callback retrieves the **Settings** object.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)<br/>[settings obj](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.settings.setSettings(instanceSettings: Settings, onComplete?: (status: Boolean, reason?: string)`|Configures the settings for the current instance. Valid settings are defined by the **Settings** object.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)<br/>[settings obj](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.settings.registerOnSaveHandler(handler: (evt: SaveEvent)`|The handler that is registered when the user selects the **Save** button. This handler should be used to create or update the underlying resource powering the content.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.settings.registerOnRemoveHandler(handler: (evt: RemoveEvent)`|The handler that is registered when the user selects the **Remove** button. This handler should be used to remove the underlying resource powering the content.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.settings.settings?view=msteams-client-js-latest&preserve-view=true)| -### Task modules namespace +## Next steps -| Function | Description | Documentation| -| -- | -- | -- | -|`microsoftTeams.tasks.startTask(taskInfo: TaskInfo, submitHandler?: (err: string, result: string)`|Takes the **TaskInfo** object as input and allows an app to open the task module. The optional **submitHandler** is registered when the task module is completed. |[function](/javascript/api/@microsoft/teams-js/microsoftteams.tasks?view=msteams-client-js-latest&preserve-view=true)<br/>[taskInfo obj](/javascript/api/@microsoft/teams-js/microsoftteams.taskinfo?view=msteams-client-js-latest&preserve-view=true)| -|`microsoftTeams.tasks.submitTask(result?: string | object, appIds?: string | string[])`|Submits the task module. The optional **result** string parameter is the result sent to the bot or the app and is typically a JSON object or serialization; The optional **appIds** string or string array parameter aids in validating that the call originated from the same appId as the one that invoked the task module.|[function](/javascript/api/@microsoft/teams-js/microsoftteams.tasks?view=msteams-client-js-latest#@microsoft-teams-js-microsoftteams-tasks-submittask&preserve-view=true)| +* Use the [TeamsJS reference](/javascript/api/overview/msteams-client) to get started with the Microsoft Teams JavaScript client SDK. +* Review the [changelog](https://github.com/OfficeDev/microsoft-teams-library-js/blob/main/packages/teams-js/CHANGELOG.md) for latest updates to TeamsJS. |
| platform | AAD Manifest Customization | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/AAD-manifest-customization.md | + + Title: Manage Azure Active Directory application in Teams Toolkit ++description: Describes Managing Azure Active Directory application in Teams Toolkit ++ms.localizationpriority: medium + Last updated : 05/20/2022+++# Azure AD manifest ++The [Azure Active Directory (Azure AD) manifest](/azure/active-directory/develop/reference-app-manifest) contains definitions of all the attributes of an Azure AD application object in the Microsoft identity platform. ++Teams Toolkit now manages Azure AD application with the manifest file as the source of truth during your Teams application development lifecycles. ++## Customize Azure AD manifest template ++You can customize Azure AD manifest template to update Azure AD application. ++1. Open `aad.template.json` in your project. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add template.png" alt-text="template"::: ++2. Update the template directly or [reference values from another file](https://github.com/OfficeDev/TeamsFx/wiki/Manage-AAD-application-in-Teams-Toolkit#Placeholders-in-AAD-manifest-template). You can see several customization scenarios here: + + * [Add an application permission](#customize-requiredresourceaccess) + * [Preauthorize a client application](#customize-preauthorizedapplications) + * [Update redirect URL for authentication response](#customize-redirect-urls) ++3. [Deploy Azure AD application changes for local environment](#deploy-azure-ad-application-changes-for-local-environment). + +4. [Deploy Azure AD application changes for remote environment](#deploy-azure-ad-application-changes-for-remote-environment). ++### Customize requiredResourceAccess ++If the Teams application requires more permissions to call API with additional permissions, you need to update `requiredResourceAccess` property in the Azure AD manifest template. You can see the following example for this property: ++```JSON ++ "requiredResourceAccess": [ + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id + "type": "Scope" // Scope is for delegated permission + }, + { + "id": "User.Export.All", + "type": "Role" // Role is for application permission + } + ] + }, + { + "resourceAppId": "Office 365 SharePoint Online", + "resourceAccess": [ + { + "id": "AllSites.Read", + "type": "Scope" + } + ] + } +] +``` ++* `resourceAppId` property is for different APIs, for `Microsoft Graph` and `Office 365` `SharePoint Online`, enter the name directly instead of UUID, and for other APIs, use UUID. ++* `resourceAccess.id` property is for different permissions, for `Microsoft Graph` and `Office 365 SharePoint Online`, enter the permission name directly instead of UUID, and for other APIs, use UUID. ++* `resourceAccess.type` property is used for delegated permission or application permission. `Scope` means delegated permission and `Role` means application permission. ++### Customize preAuthorizedApplications ++You can use `preAuthorizedApplications` property to authorize a client application to indicate that the API trusts the application and users don't consent when the client calls it exposed API. You can see the following example for this property: ++```JSON ++ "preAuthorizedApplications": [ + { + "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264", + "permissionIds": [ + "{{state.fx-resource-aad-app-for-teams.oauth2PermissionScopeId}}" + ] + } + ... + ] +``` ++`preAuthorizedApplications.appId` property is used for the application you want to authorize. If you don't know the application ID but only knows the application name, you can go to Azure portal and follow the steps to search the application to find the ID : ++1. Go to [Azure portal](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) and open application registrations. ++1. Select **All applications** and search for the application name. ++1. Select the application name and get the application ID from the overview page. ++### Customize redirect URLs ++ Redirect URLs are used while returning authentication responses such as tokens after successful authentication. You can customize redirect URLs using property `replyUrlsWithType`, for example, to add `https://www.examples.com/auth-end.html` as redirect URL, you can add it as the following example: ++``` JSON +"replyUrlsWithType": [ + ... + { + "url": "https://www.examples.com/auth-end.html", + "type": "Spa" + } +] +``` ++## Azure AD manifest template placeholders ++The Azure AD manifest file contains placeholder arguments with {{...}} statements it's replaced during build for different environments. You can build references to config file, state file and environment variables with the placeholder arguments. ++### Reference state file values in Azure AD manifest template ++The State file is located in `.fx\states\state.xxx.json` (xxx represents different environment). The following example shows typical state file: ++``` JSON +{ + "solution": { + "teamsAppTenantId": "uuid", + ... + }, + "fx-resource-aad-app-for-teams": { + "applicationIdUris": "api://xxx.com/uuid", + ... + } + ... +} +``` ++You can use this placeholder argument in the Azure AD manifest: `{{state.fx-resource-aad-app-for-teams.applicationIdUris}}` to refer `applicationIdUris` value in `fx-resource-aad-app-for-teams` property. ++### Reference config file values in Azure AD manifest template ++The Config file is located in `.fx\configs\config.xxx.json` (xxx represents different environment). The following example shows config file: ++``` JSON +{ + "$schema": "https://aka.ms/teamsfx-env-config-schema", + "description": "description.", + "manifest": { + "appName": { + "short": "app", + "full": "Full name for app" + } + } +} +``` ++You can use the placeholder argument in the Azure AD manifest: `{{config.manifest.appName.short}}` to refer `short` value. ++### Reference environment variable in Azure AD manifest template ++Sometimes you don't want to hardcode the values in Azure AD manifest template. For example, when the value is a secret. Azure AD manifest template file supports reference environment variables values. You can use syntax `{{env.YOUR_ENV_VARIABLE_NAME}}` in parameter values to tell the tooling to resolve the value current environment variable. ++## Author and preview Azure AD manifest with code lens ++Azure AD manifest template file has code lens to review and edit. +++### Azure AD manifest template file ++At the beginning of the Azure AD manifest template file, there's a preview code lens. Select the code lens, it generates Azure AD manifest based on the environment you selected. +++### Placeholder argument code lens ++Placeholder argument code lens helps you to take quick look of the values for local debug and develop environment. If your mouse hover on the placeholder argument, it shows tooltip box for the values of all the environment. +++### Required resource access code lens ++It's different from official [Azure AD manifest schema](/azure/active-directory/develop/reference-app-manifest) that `resourceAppId` and `resourceAccess` ID in `requiredResourceAccess` property only supports UUID, Azure AD manifest template in Teams Toolkit also supports user readable strings for `Microsoft Graph` and `Office 365 SharePoint Online` permissions. If you enter UUID, code lens shows user readable strings, otherwise, it shows UUID. +++### Pre-authorized applications code lens ++Code lens shows the application name for the per-authorized application ID for the `preAuthorizedApplications` property. ++## Deploy Azure AD application changes for local environment ++1. Select `Preview` code lens in `aad.template.json`. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add deploy1.png" alt-text="deploy1"::: ++2. Select `local` environment. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add deploy2.png" alt-text="deploy2"::: ++3. Select `Deploy Azure AD Manifest` code lens in `aad.local.json`. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add deploy3.png" alt-text="deploy3"::: ++4. The changes for Azure AD application used in local environment are deployed. + +## Deploy Azure AD application changes for remote environment ++1. Open the command palette and select: `Teams: Deploy Azure Active Directory application manifest`. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add deploy4.png" alt-text="deploy4"::: ++2. You can also right click on the `aad.template.json` and select `Deploy Azure Active Directory application manifest` from the context menu. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add deploy5.png" alt-text="deploy5"::: ++## View Azure AD application on the Azure portal ++1. Copy the Azure AD application client ID from `state.xxx.json` (xxx is the environment name that you have deployed the Azure AD application) file in the `fx-resource-aad-app-for-teams` property. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add view1.png" alt-text="view1"::: ++2. Go to [Azure portal](https://ms.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) and log-in to Microsoft 365 account. + + > [!NOTE] + > Ensure that login credentials of Teams application and M365 account are same. ++3. Open [app registrations page](https://ms.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps), search the Azure AD application using client ID that you copied before. + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add view2.png" alt-text="view2"::: ++4. Select Azure AD application from search result to view the detail information. + +5. In Azure AD app information page, select `Manifest` menu to view manifest of this application. The schema of the manifest is same as the one in `aad.template.json` file. For more information about manifest, see [Azure Active Directory application manifest](/azure/active-directory/develop/reference-app-manifest). + + :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add view3.png" alt-text="view3"::: ++6. You can select **Other Menu** to view or configure Azure AD application through portal. + +## Use an existing Azure AD application ++You can use the existing Azure AD application for the Teams project, for more information, see [Use an existing Azure AD application for your Teams application](https://github.com/OfficeDev/TeamsFx/wiki/Customize-provision-behaviors#use-an-existing-aad-app-for-your-teams-app). ++## Azure AD application in Teams application development lifecycle ++You need to interact with Azure AD application during various stages of your Teams application development lifecycle. ++1. **To create Project** ++ You can create a project with Teams Toolkit that comes with SSO support by default such as `SSO-enabled tab`. For more information to create a new app, see [create new Teams application using Teams Toolkit](create-new-project.md). An Azure AD manifest file is automatically created for you: `templates\appPackage\aad.template.json`. Teams Toolkit creates or updates the Azure AD application during local development or while you move the application to the cloud. ++2. **To add SSO to your Bot or Tab** ++ After you create a Teams application without SSO built-in, Teams Toolkit incrementally helps you to add SSO for the project. As a result, An Azure AD manifest file is automatically created for you: `templates\appPackage\aad.template.json`. ++ Teams Toolkit creates or updates the Azure AD application during next local debug session or while you move the application to the cloud. ++3. **To build Locally** ++ Teams Toolkit performs the following functions during local development (known as F5): ++ * Read the `state.local.json` file to find an existing Azure AD application. If an Azure AD application already exists, Teams Toolkit re-uses the existing Azure AD application otherwise you need to create a new application using the `aad.template.json` file ++ * Initially ignores some properties in the manifest file that requires additional context (such as replyUrls property that requires a local debug endpoint) during the creation of a new Azure AD application with the manifest file. ++ * After the local dev environment startup successfully, the Azure AD application's identifierUris, replyUrls, and other properties that are not available during creation stage are updated accordingly ++ * The changes you have done to your Azure AD application are loaded during next local debug session. You can see [Azure AD application changes](https://github.com/OfficeDev/TeamsFx/wiki/) to apply changes manually Azure AD application changes ++4. **To provision for cloud resources** ++ You need to provision cloud resources and deploy your application while moving your application to the cloud. At the stages, like local development, Teams Toolkit will: ++ * Read the `state.{env}.json` file to find an existing Azure AD application. If an Azure AD application already exists, Teams Toolkit re-uses the existing Azure AD application otherwise you need to create a new application using the `aad.template.json` file ++ * Initially ignores some properties in the manifest file that requires additional context (such as replyUrls property requires frontend or bot endpoint) during the creation of a new Azure AD application with the manifest file ++ * After other resources provision completes, the Azure AD application's identifierUris and replyUrls are updated accordingly to the correct endpoints ++5. **To build application** ++ * Deploy to the cloud command deploys your application to the provisioned resources. It doesn't include deploying Azure AD application changes you made ++ * You can see, [Deploy Azure AD application changes for remote environment](#deploy-azure-ad-application-changes-for-remote-environment) to deploy Azure AD application changes for remote environment ++ * Teams Toolkit updates the Azure AD application according to the Azure AD manifest template file ++## Limitations ++1. Teams Toolkit extension doesn't supports all the properties listed in Azure AD manifest schema. + + The following table lists the properties that aren't supported in Teams Toolkit extension: ++ |**Not supported properties**|**Reason**| + |--|-| + |passwordCredentials|Not allowed in manifest| + |createdDateTime|Readonly and can't change| + |logoUrl|Readonly and can't change| + |publisherDomain|Readonly and can't change| + |oauth2RequirePostResponse|Doesn't exist in Graph API| + |oauth2AllowUrlPathMatching|Doesn't exist in Graph API| + |samlMetadataUrl|Doesn't exist in Graph API| + |orgRestrictions|Doesn't exist in Graph API| + |certification|Doesn't exist in Graph API| ++2. Currently `requiredResourceAccess` property can use user readable resource application name or permission name strings only for `Microsoft Graph` and `Office 365 SharePoint Online` APIs. For other APIs, you need to use UUID instead. You can follow these steps to retrieve IDs from Azure portal: ++ * Register a new Azure AD application on [Azure portal](https://ms.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) + * Select `API permissions` from the Azure AD application page + * Select `add a permission` to add the permission you want + * Select `Manifest`, from the `requiredResourceAccess` property, you can find the IDs of API and permissions ++## See also ++* [Preview and Customize app manifest in Toolkit](TeamsFx-preview-and-customize-app-manifest.md) |
| platform | Teamsfx CLI | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-CLI.md | Last updated 11/29/2021 # TeamsFx Library -Microsoft Teams Framework (TeamsFx) is a library encapsulating common functionality and integration patterns (like simplified access to Microsoft Identity). You can build apps for Microsoft Teams with zero configuration. +Microsoft Teams Framework (TeamsFx) is a library encapsulating common functionality and integration patterns, such as simplified access to Microsoft Identity. You can build apps for Microsoft Teams with zero configuration. Here's a list of main TeamsFx features: -* **TeamsFx Collaboration**: Let developers and project owner invite other collaborators to the TeamsFx project. You can collaborate to debug and deploy a TeamsFx project. +* **TeamsFx Collaboration**: Lets developers and project owner invite other collaborators to the TeamsFx project. You can collaborate to debug and deploy a TeamsFx project. -* **TeamsFx CLI**: It accelerates Teams application development. It also enables CI/CD scenario where you can integrate CLI in scripts for automation. +* **TeamsFx CLI**: Accelerates Teams application development. It also enables CI/CD scenario where you can integrate CLI in scripts for automation. -* **TeamsFx SDK**: TeamsFx Software Development Kit (SDK) is the main TeamsFx code library encapsulating simple authentication for both client and server-side code tailored for Teams developers. +* **TeamsFx SDK**: Provides access to database, such as the primary TeamsFx code library containing simple authentication for both client and server-side code tailored for Teams developers. ## TeamsFx command line interface TeamsFx CLI is a text-based command line interface that accelerates Teams application development. It aims to provide keyboard centric experience while building Teams applications. It also enables CI/CD scenario where you can integrate CLI in scripts for automation. For more information, see:- * [Source code](https://github.com/OfficeDev/TeamsFx/tree/dev/packages/cli) * [Package (NPM)](https://www.npmjs.com/package/@microsoft/teamsfx-cli) Install `teamsfx-cli` from `npm` and run `teamsfx -h` to check all available com | Command | Description | |-|-| | `teamsfx new`| Create new Teams application.|+| `teamsfx add`| Adds features to your Teams application.| | `teamsfx account`| Manage cloud service accounts. The supported cloud services are 'Azure' and 'Microsoft 365'. | | `teamsfx env` | Manage environments. |-| `teamsfx capability`| Add new capabilities to the current application.| -| `teamsfx resource` | Manage the resources in the current application.| | `teamsfx provision` | Provision cloud resources in the current application.| | `teamsfx deploy` | Deploy the current application. | | `teamsfx package` | Build your Teams app into package for publishing.| Install `teamsfx-cli` from `npm` and run `teamsfx -h` to check all available com ## `teamsfx new` -By default, `teamsfx new` goes into interactive mode and guides you through the process of creating a new Teams application. You can also work with non-interactive mode by setting `--interactive` flag to `false`. +By default, `teamsfx new` is in interactive mode and guides to create new Teams application. You can work in the non-interactive mode by setting `--interactive` flag to `false`. -| `teamsFx new` Command | Description | +| Command | Description | |:- |:-| | `teamsfx new template <template-name>` | Create an app from an existing template | | `teamsfx new template list` | List all the available templates | By default, `teamsfx new` goes into interactive mode and guides you through the |:- |:-|:-| |`--app-name` | Yes| Name of your Teams application.| |`--interactive`| No | Select the options interactively. The options are `true` and `false` and default value is `true`.|-|`--capabilities`| No| Choose Teams application capabilities, the multiple options are `tab`, `bot`, `messaging-extension` and `tab-spfx`. The default value is `tab`.| +|`--capabilities`| No| Choose Teams application capabilities, the options are `tab`, `tab-non-sso`, `tab-spfx`, `bot`, `message-extension`, `notification`, `command-bot`, `sso-launch-page`, `search-app`. The default value is `tab`.| |`--programming-language`| No| Programming language for the project. The options are `javascript` or `typescript` and default value is `javascript`.| |`--folder`| No | Project directory. A sub folder with your app name is created under this directory. The default value is `./`.|-|`--spfx-framework-type`| No| Applicable if `Tab(SPfx)` capability is selected. Frontend Framework. The options are `none` and `react`, and default value is `none`.| -|`--spfx-web part-name`| No | Applicable if `Tab(SPfx)` capability is selected. The default value is "helloworld".| -|`--spfx-web part-desp`| No | Applicable if `Tab(SPfx)` capability is selected. The default value is "helloworld description". | -|`--azure-resources`| No| Applicable if contains `tab` capability. Add Azure resources to your project. The multiple options are `sql` (Azure SQL Database) and `function` (Azure Functions). | +|`--spfx-framework-type`| No| Applicable if `SPFx tab` capability is selected. Frontend Framework. The options are `none`, `react` and `minimal`, and default value is `none`.| +|`--spfx-web part-name`| No | Applicable if `SPFx tab` capability is selected. The default value is "helloworld".| +|`--bot-host-type-trigger`| No | Applicable if `Notification bot` capability is selected. The options are `http-restify`, `http-functions`, and `timer-functions`. The default value is `http-restify`.| ### Scenarios for `teamsfx new` -You can use interactive mode to create a Teams app.The scenarios on controlling all the parameters with `teamsfx new` are as follows: +You can use interactive mode to create a Teams app. The following list provides scenarios on controlling all the parameters with `teamsfx new`: -#### Tab app hosted on SPFx using React +* Http triggered notification bot with restify server -```bash -teamsfx new --interactive false --app-name newspfxapp --capabilities tab-spfx --spfx-framework-type react -``` + ```bash + teamsfx new --interactive false --capabilities "notification" --bot-host-type-trigger "http-restify" --programming-language "typescript" --folder "./" --app-name MyAppName + ``` -#### Teams app in JavaScript with tab, bot capabilities and Azure Functions +* Teams command and response bot -```bash -teamsfx new --interactive false --app-name newtabbotapp --capabilities tab bot --programming-language javascript --azure-resources function -``` + ```bash + teamsfx new --interactive false --capabilities "command-bot" --programming-language "typescript" --folder "./" --app-name myAppName + ``` -#### Teams tab app with Azure Functions and Azure SQL +* Tab app hosted on SPFx using React -```bash -teamsfx new --interactive false app-name newapp --azure-resources sql function --programming-language typescript -``` + ```bash + teamsfx new --interactive false --app-name newspfxapp --capabilities tab-spfx --spfx-framework-type react + ``` ++## `teamsfx add` ++The following table lists diffetent features to your Teams application along with their descrition. ++| Command | Description | +|:- |:-| +| `teamsfx add notification` | Send notification to Microsoft Teams through various triggers. | +| `teamsfx add command-and-response` | Respond to simple commands in Microsoft Teams chat.| +| `teamsfx add sso-tab` | Teams identity aware webpages embedded in Microsoft Teams.| +| `teamsfx add tab` | Hello world webpages embedded in Microsoft Teams.| +| `teamsfx add bot` | Hello world chatbot to run simple and repetitive tasks by user. | +| `teamsfx add message-extension` | Hello world message extension allowing interactions through buttons and forms. | +| `teamsfx add azure-function`| A serverless, event-driven compute solution that allows you to write less code. | +| `teamsfx add azure-apim` | A hybrid, multicloud management platform for APIs across all environments.| +| `teamsfx add azure-sql` | An always-up-to-date relational database service built for the cloud. | +| `teamsfx add azure-keyvault` | A cloud service for securely storing and accessing secrets. | +| `teamsfx add sso` | Develop a Single Sign-On feature for Teams Launch pages and Bot capability. | +| `teamsfx add api-connection [auth-type]` | Connect to an API with authentication support using TeamsFx SDK. | +| `teamsfx add cicd` | Add CI/CD Workflows for GitHub, Azure DevOps or Jenkins.| ## `teamsfx account` -Manage cloud service accounts. The supported cloud services are `Azure` and `Microsoft 365`. +The following table lists the cloud service accounts,such as Azure and Microsoft 365. -| `teamsFx account` Command | Description | +| Command | Description | |:- |:-|-| `teamsfx account login <service>` | Log in to the selected cloud service. | -| `teamsfx account logout <service>` | log out of selected cloud service. | +| `teamsfx account login <service>` | Log in to the selected cloud service. Service options are M365 or Azure. | +| `teamsfx account logout <service>` | log out of selected cloud service. Service options are M365 or Azure. | | `teamsfx account set --subscription` | Update account settings to set a subscription ID. | ## `teamsfx env` -Manage the environments. +The following table lists the different environments. -| `teamsfx env` Command | Description | +| Command | Description | |:- |:-| | `teamsfx env add <new_env_name> --env <existing_env_name>` | Add a new environment by copying from the specified environment. | | `teamsfx env list` | List all environments. | ### Scenarios for `teamsfx env` -The scenarios for `teamsfx env` are as follows: --#### Create a new environment --Add a new environment by copying from the existing dev environment: +Create a new environment by copying from the existing dev environment: ```bash teamsfx env add staging --env dev ``` -## `teamsfx capability` --Add new capabilities to the current application. --| `teamsFx capability` Command | Description | -|:- |:-| -| `teamsfx capability add tab` | Add tab | -| `teamsfx capability add bot` | Add bot | -| `teamsfx capability add messaging-extension`| Add messagE extension | --> [!NOTE] -> If your project includes a bot, message extension can't be added and it applies vice versa. You can include both bot and message extensions in your project while creating a new Teams app project. --## `teamsfx resource` --Manage the resources in the current application. Supported `<resource-type>` are: `azure-sql`, `azure-function` and `azure-apim` . --| `teamsFx resource` Command | Description | -|:- |:-| -| `teamsfx resource add <resource-type>` | Add resource into current application.| -| `teamsfx resource show <resource-type>` | Show configuration details of the resource. | -| `teamsfx resource list` | List all the resources in the current application. | --### Parameters for `teamsfx resource add azure-function` --| Parameter | Requirement | Description | -|- |-|-| -|`--function-name`| Yes | Provide a function name. The default value is `getuserprofile`. | --### Parameters for `teamsfx resource add azure-sql` --#### `--function-name` --| Parameter | Requirement | Description | -|:- |:-|:-| -|`--function-name`| Yes | Provide a function name. The default value is `getuserprofile`. | --> [!NOTE] -> The function name is verified as SQL and needs to be accessed from server workload. If your project doesn't contain `Azure Functions`, create one for you. --### Parameters for `teamsfx resource add azure-apim` --> [!TIP] -> The options take effect when you try to use an existing `APIM` instance. By default, you don't have to specify any options and it creates a new instance during `teamsfx provision` step. --| Parameter | Requirement | Description | -|:- |:-|:-| -|`--subscription`| Yes | Select an Azure subscription| -|`--apim-resource-group`| Yes| The name of resource group. | -|`--apim-service-name`| Yes | The name of the API management service instance. | -|`--function-name`| Yes | Provide a function name. The default value is `getuserprofile`. | --> [!NOTE] -> `Azure API Management` needs to work with `Azure Functions`. If your project doesn't contain `Azure Functions`, you can create one. - ## `teamsfx provision` Provision the cloud resources in the current application. +| `teamsFx provision` Command | Description | +|:- |:-| +| `teamsfx provision manifest` | Provision a Teams App in Teams Developer portal with corresponding information specified in the given manifest file. | + ### Parameters for `teamsfx provision` | Parameter | Requirement | Description | Provision the cloud resources in the current application. ## `teamsfx deploy` -This command is used to deploy the current application. By default it deploys entire project but it's also possible to deploy partially. The multiple options are `frontend-hosting`, `function`, `apim`, `teamsbot`, and `spfx`. +This command is used to deploy the current application. By default it deploys entire project but it's also possible to deploy partially. The options are `frontend-hosting`, `function`, `apim`, `bot`, `spfx`, `aad-manifest` and `manifest`. ### Parameters for `teamsfx deploy` This command is used to deploy the current application. By default it deploys en |`--open-api-document`| No | Applicable when there is APIM resource in the project. The open API document file path. | |`--api-prefix`| No | Applicable when there is APIM resource in the project. The API name prefix. The default unique name of the API is `{api-prefix}-{resource-suffix}-{api-version}`. | |`--api-version`| No | Applicable when there is APIM resource in the project. The API version. |+|`--include-app-manifest`| No | Whether to deploy app manifest to Teams platform. Options are `yes` and `not`. The default value is `no`. | +|`--include-aad-manifest`| No | Whether to deploy aad manifest. Options are `yes` and `not`. The default value is `no`. | + ## `teamsfx validate` Preview the current application from local or remote. |`--browser`| No | The browser to open Teams web client. The options are `chrome`, `edge` and `default` such as system default browser and the value is `default`. | |`--browser-arg`| No | Argument to pass to the browser, requires --browser, can be used multiple times, for example, --browser-args="--guest" | |`--sharepoint-site`| No | SharePoint site URL, such as `{your-tenant-name}.sharepoint.com` for SPFx project remote preview. |+|`--m365-host`| Preview the application in Teams, Outlook or Office. Options are `teams`, `outlook` and `office`. The default value is `teams`. | ### Scenarios for `teamsfx preview` -#### Local Preview +The following list provides the common scenarios for`teamsfx preview: -Dependencies: +* Local Preview -* Node.js -* .NET SDK -* Azure Functions Core Tools + Dependencies: -```bash -teamsfx preview --local -teamsfx preview --local --browser chrome -``` + * Node.js + * .NET SDK + * Azure Functions Core Tools -#### Remote Preview + ```bash + teamsfx preview --local + teamsfx preview --local --browser chrome + ``` -```bash -teamsfx preview --remote -teamsfx preview --remote --browser edge -``` +* Remote Preview ++ ```bash + teamsfx preview --remote + teamsfx preview --remote --browser edge + ``` -> [!NOTE] -> The logs of the background services, such as React is saved in `~/.fx/cli-log/local-preview/`. + > [!NOTE] + > The logs of the background services, such as React is saved in `~/.fx/cli-log/local-preview/`. ## `teamsfx config` -Manage the configuration data either in user scope or project scope. +The configuration data is either in user scope or project scope. -| `teamsfx config` Command | Description | +| Command | Description | |:- |:-| | `teamsfx config get [option]` | View the configuration value of option | | `teamsfx config set <option> <value>` | Update the configuration value of option | Manage the configuration data either in user scope or project scope. |`--folder`| No | Project directory. This is used for get or set project configuration. The default value is `./`. | |`--global`| No | Cope of configuration. If this is true, the scope is limited to user scope instead of project scope. The default value is `false`. At present, the supported global configurations include `telemetry`, `validate-dotnet-sdk`, `validate-func-core-tools`, `validate-node`. | -### Scenerios for `teamsfx config` +### Scenarios for `teamsfx config` -Secrets in `.userdata` file are encrypted, `teamsfx config` and can help you to view or update the values. +The secrets in `.userdata` file are encrypted, `teamsfx config` and can help you view or update required values. -#### Stop sending telemetry data +* Stop sending telemetry data -```bash -teamsfx config set telemetry off -``` + ```bash + teamsfx config set telemetry off + ``` -#### Disable environment checker +* Disable environment checker -There are three configuration to turn on or off Node.js, .NET SDK and Azure Functions Core Tools validation, and all of them are enabled by default. You can set the configuration to "off" if you don't need the dependencies validation and want to install the dependencies by yourself. Check the following guides: + There are three configuration to turn on or off Node.js, .NET SDK and Azure Functions Core Tools validation, and all of them are enabled by default. You can set the configuration to "off" if you don't need the dependencies validation and want to install the dependencies by yourself. Check the following guides: -* [Node.js installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-nodejs) -* [.NET SDK installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-net-sdk) -* [Azure Functions Core Tools installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-azure-functions-core-tools). + * [Node.js installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-nodejs) + * [.NET SDK installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-net-sdk) + * [Azure Functions Core Tools installation guide](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/vscode-extension/envchecker-help.md#how-to-install-azure- functions-core-tools). -To disable .NET SDK validation, you can use the following command: + To disable .NET SDK validation, you can use the following command: -```bash -teamsfx config set validate-dotnet-sdk off -``` + ```bash + teamsfx config set validate-dotnet-sdk off + ``` -To enable .NET SDK validation, you can use the following command: + To enable .NET SDK validation, you can use the following command: -```bash -teamsfx config set validate-dotnet-sdk on -``` + ```bash + teamsfx config set validate-dotnet-sdk on + ``` -#### View all the user scope configuration +* View all the user scope configuration -```bash -teamsfx config get -g -``` + ```bash + teamsfx config get -g + ``` -#### View all the configuration in project +* View all the configuration in project -The secret is automatically decrypted: + The secret is automatically decrypted: -```bash -teamsfx config get --env dev -``` + ```bash + teamsfx config get --env dev + ``` -#### Update the secret configuration in project +* Update the secret configuration in project -```bash -teamsfx config set fx-resource-aad-app-for-teams.clientSecret xxx --env dev -``` + ```bash + teamsfx config set fx-resource-aad-app-for-teams.clientSecret xxx --env dev + ``` ## `teamsfx permission` -TeamsFx CLI provides `teamsFx permission` commands for collaboration scenario. +TeamsFx CLI provides `teamsFx permission` commands for collaboration scenarios. -| `teamsFx permission` command | Description | +| command | Description | |:|-| | `teamsfx permission grant --env --email` | Grant permission for collaborator's Microsoft 365 account for the project of a specified environment. | | `teamsfx permission status` | Show permission status for the project | TeamsFx CLI provides `teamsFx permission` commands for collaboration scenario. ### Scenarios for `teamsfx permission` -The permissions for `TeamsFx` projects are as follows: +The following list provides required permissions for `TeamsFx` projects: -#### Grant Permission +* Grant Permission -Project creator and collaborators can use `teamsfx permission grant` command to add a new collaborator to the project: + Project creator and collaborators can use `teamsfx permission grant` command to add a new collaborator to the project: -```bash -teamsfx permission grant --env dev --email user-email@user-tenant.com -``` + ```bash + teamsfx permission grant --env dev --email user-email@user-tenant.com + ``` -After receiving required permission, project creator and collaborators can share the project with the new collaborator by GitHub, and the new collaborator can have all permission for Microsoft 365 account. + After receiving required permission, project creator and collaborators can share the project with the new collaborator by GitHub, and the new collaborator can have all permission for Microsoft 365 account. -#### Show Permission Status +* Show Permission Status -Project creator and collaborators can use `teamsfx permission status` command to view his Microsoft 365 account permission for specific env: + Project creator and collaborators can use `teamsfx permission status` command to view his Microsoft 365 account permission for specific env: -```bash -teamsfx permission status --env dev -``` + ```bash + teamsfx permission status --env dev + ``` -#### List All Collaborators +* List All Collaborators -Project creator and collaborators can use `teamsfx permission status` command to view all collaborators for specific env: + Project creator and collaborators can use `teamsfx permission status` command to view all collaborators for specific env: -```bash -teamsfx permission status --env dev --list-all-collaborators -``` + ```bash + teamsfx permission status --env dev --list-all-collaborators + ``` -#### E2E Collaboration work flow in CLI +* E2E Collaboration work flow in CLI -As a project creator: + * As a project creator: -* To create a new TeamsFx tab or bot project, and select Azure as the host type: + * To create a new TeamsFx tab or bot project, and select Azure as the host type: - ```bash - teamsfx new --interactive false --app-name newapp --host-type azure - ``` + ```bash + teamsfx new --interactive false --app-name newapp --host-type azure + ``` -* To login to Microsoft 365 account and Azure account: + * To login to Microsoft 365 account and Azure account: - ```bash - teamsfx account login azure - teamsfx account login Microsoft 365 - ``` + ```bash + teamsfx account login azure + teamsfx account login Microsoft 365 + ``` -* To provision your project: + * To provision your project: - ```bash - teamsfx provision - ``` + ```bash + teamsfx provision + ``` -* To view collaborators: + * To view collaborators: - ```bash - teamsfx permission status --env dev --list-all-collaborators - ``` + ```bash + teamsfx permission status --env dev --list-all-collaborators + ``` - :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/permission-status-all-1.png" alt-text="permission-1"::: + :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/permission-status-all-1.png" alt-text="permission-1"::: -* To add another account as collaborator. Ensure the added account is under the same tenant: + * To add another account as collaborator. Ensure the added account is under the same tenant: - ```bash - teamsfx permission grant --env dev --email user-email@user-tenant.com - ``` + ```bash + teamsfx permission grant --env dev --email user-email@user-tenant.com + ``` - :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/permission-grant-1.png" alt-text="permission"::: + :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/permission-grant-1.png" alt-text="permission"::: -* To push your project to GitHub + * To push your project to GitHub -As a Project Collaborator: + * As a Project Collaborator: -* Clone the project from GitHub. -* Login to Microsoft 365 account. Ensure that the same Microsoft 365 account is added: + * Clone the project from GitHub. + * Login to Microsoft 365 account. Ensure that the same Microsoft 365 account is added: - ```bash - teamsfx account login Microsoft 365 - ``` + ```bash + teamsfx account login Microsoft 365 + ``` -* Login to Azure account with contributor permission for all Azure resources. + * Login to Azure account with contributor permission for all Azure resources. - ```bash - teamsfx account login azure - ``` + ```bash + teamsfx account login azure + ``` -* Check permission status. You should find yourself have the owner permission of the project: + * Check permission status. You should find yourself have the owner permission of the project: - ```bash - teamsfx permission status --env dev - ``` + ```bash + teamsfx permission status --env dev + ``` -  +  -* Update Tab code, and deploy the project to remote. -* Launch remote and the project should work fine. + * Update Tab code, and deploy the project to remote. + * Launch remote and the project should work fine. ## See also |
| platform | Teamsfx SDK | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-SDK.md | const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]); const profile = await graphClient.api("/me").get(); ``` +</details> ++<br> ++<details> +<summary><b>Create API client to call existing API in Bot or Azure Function</b></summary> +++ </details> <br> Use `axios` library to make HTTP request to Azure Function. ```ts const teamsfx = new TeamsFx();-const token = teamsfx.getCredential().getToken(""); // Get SSO token for the use -// Call API hosted in Azure Functions on behalf of user -const apiEndpoint = teamsfx.getConfig("apiEndpoint"); -const response = await axios.default.get(apiEndpoint + "api/httptrigger1", { - headers: { - authorization: "Bearer " + token, - }, -}); +const credential = teamsfx.getCredential(); //Create an API Client that uses SSO token to authenticate requests +const apiClient = CreateApiClient(teamsfx.getConfig("apiEndpoint")), +new BearerTokenAuthProvider(async () => (await credential.getToken(""))!.token);// Call API hosted in Azure Functions on behalf of user +const response = await apiClient.get("/api/" + functionName); ``` </details> |
| platform | Teamsfx Manifest Customization | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-manifest-customization.md | - Title: Customize Teams App Manifest in Teams Toolkit- -description: Customize Teams App Manifest -- Previously updated : 11/29/2021---# Customize app manifest in Toolkit --Teams Toolkit consists of the following manifest template files under `manifest.template.json` folder across local and remote environments: --* `manifest.template.json` -* `templates/appPackage` ---## Prerequisite --* Install the [latest version of Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension). --> [!TIP] -> Ensure you have Teams app project opened in Visual Studio Code. --During local debug or provision, Teams Toolkit loads manifest from `manifest.template.json`, with configurations from `state.{env}.json`, `config.{env}.json`, and creates teams app in [Dev Portal](https://dev.teams.microsoft.com/apps). ---## Placeholders supported in manifest.template.json --* `{{state.xx}}` is pre-defined placeholder and it's value is resolved by Teams Toolkit, defined in `state.{env}.json`. Ensure not to modify the values in state.{env}.json -* `{{config.manifest.xx}}` is customized placeholder and it's value is resolved from `config.{env}.json` -- 1. You can add a customized parameter as follows: - 1. Add a placeholder in manifest.template.json with pattern: `{{config.manifest.xx}}` - 2. Add a config value in config.{env}.json -- ```json - { - "manifest": { - "KEY": "VALUE" - } - } - ``` -- 2. You can navigate to configuration file by selecting any one of the config placeholder **Go to config file** or **View the state file** in `manifest.template.json` --## See also --[Preview Teams App Manifest in Teams Toolkit](TeamsFx-manifest-preview.md) |
| platform | Teamsfx Manifest Preview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-manifest-preview.md | - Title: Preview Teams App Manifest in Teams Toolkit- -description: Preview Teams App Manifest -- Previously updated : 11/29/2021---# Preview app manifest in Toolkit --The manifest template file `manifest.template.json` is available under `templates/appPackage` folder after scaffolding. The Template file with placeholders, and the actual values is resolved by Teams Toolkit from files under `.fx/configs` and `.fx/states` for different environments. --## Prerequisite --* Install the [latest version of Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) --> [!TIP] -> Ensure you have Teams app project opened in Visual Studio code. --## Preview manifest --To preview manifest with real content, Teams Toolkit generates preview manifest files under `build/appPackage` folder: --```text -ΓööΓöÇΓöÇΓöÇbuild - ΓööΓöÇΓöÇΓöÇappPackage - Γö£ΓöÇΓöÇΓöÇappPackage.{env}.zip - Zipped app package of remote teams app - Γö£ΓöÇΓöÇΓöÇappPackage.local.zip - Zipped app package of local team app - Γö£ΓöÇΓöÇΓöÇmanifest.{env}.json - Previewed manifest of remote teams app - ΓööΓöÇΓöÇΓöÇmanifest.local.json - Previewed manifest of local teams app -``` --### Preview local manifest file --To preview manifest file of local teams app, you can press **F5** to run local debug. It generates default local settings for you, then the app package and preview manifest builds under `build/appPackage` folder. --You can also preview local manifest by following the steps: --1. Select **Preview** in the codelens of `manifest.template.json` file and select **local** -2. Select **Preview manifest file** on the menu bar of `manifest.template.json` file -3. Select **Zip Teams metadata package** in Treeview and select **local** --The preview local appears as shown in the image: ---### Preview manifest in remote environment --To preview manifest file of remote teams app, select **Provision in the cloud** in **DEVELOPMENT** panel of Teams Toolkit extension Treeview, or trigger **Teams: Provision in the cloud** from command palette. It generates configuration for remote teams app, and builds package and preview manifest under `build/appPackage` folder. --You can also preview manifest in remote environment by following the steps: --1. Select **Preview** in the codelens of `manifest.template.json` file -2. Select **Preview manifest file** on the menu bar of `manifest.template.json` file -3. Select **Zip Teams metadata package** in Treeview -4. Select your environment --If there are more than one environment, you need to select the environment you want to preview as shown in the image: ---## Sync local changes to Developer Portal --After previewing the manifest file, you can sync your local changes to Developer Portal by following the steps: --1. Select **Update to Teams platform** on the top left corner of `manifest.{env}.json` -2. Select **Teams: Update manifest to Teams platform** on the menu bar of `manifest.{env}.json` -- You can also trigger **Teams: Update manifest to Teams platform** from command palette: -- :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/pre.png" alt-text="tree view"::: --> [!NOTE] -> Trigger from editor codelens or **title** updates current manifest file to Teams platform. Trigger from command palette requires selecting target environment -- --If the manifest file is outdated due to configuration file change or template change, select any one of the following action: --* **Preview only**: Local manifest file is overwritten according to current configuration -* **Preview and update**: Local manifest file is overwritten according to current configuration and also updated to Teams platform -* **Cancel**: No action is taken -----> [!NOTE] -> The changes are updated in Dev Portal. Any manual updates in dev portal are overwritten. --## See also --[Customize Teams App Manifest in Teams Toolkit](TeamsFx-manifest-customization.md) |
| platform | Teamsfx Multi Env | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-multi-env.md | The following table lists the common scenarios for customized resource provision | Reuse existing Azure AD app for Teams app | <ul> <li>`auth` section in`.fx/config.<envName>.json`</li> </ul> | [Use an existing Azure AD app for your Teams app](provision.md#use-an-existing-azure-ad-app-for-your-teams-app) | | Reuse existing Azure AD app for bot | <ul> <li>`bot` section in`.fx/config.<envName>.json`</li> </ul> | [Use an existing Azure AD app for your bot](provision.md#use-an-existing-azure-ad-app-for-your-bot) | | Skip adding user while provisioning SQL | <ul> <li>`skipAddingSqlUser` property in`.fx/config.<envName>.json`</li> </ul> | [Skip adding user for SQL database](provision.md#skip-adding-user-for-sql-database) |-| Customize app manifest | <ul> <li>`templates/manifest.template.json`</li> <li>`manifest` section in `.fx/config.<envName>.json`</li> </ul> | [Customize Teams App Manifest in Teams Toolkit](TeamsFx-manifest-customization.md) | +| Customize app manifest | <ul> <li>`templates/manifest.template.json`</li> <li>`manifest` section in `.fx/config.<envName>.json`</li> </ul> | [Preview app manifest in Toolkit](TeamsFx-preview-and-customize-app-manifest.md)| ## Scenarios |
| platform | Teamsfx Preview And Customize App Manifest | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/TeamsFx-preview-and-customize-app-manifest.md | + + Title: Teams App Manifest in Teams Toolkit ++description: Teams App Manifest ++ms.localizationpriority: medium + Last updated : 05/13/2022+++# Edit Teams app manifest ++The manifest template file `manifest.template.json` is available under `templates/appPackage` folder after scaffolding. The template file with placeholders, and the actual values are resolved by Teams Toolkit using files under `.fx/configs` and `.fx/states` for different environments. ++**To preview manifest with actual content, Teams Toolkit generates preview manifest files under `build/appPackage` folder**: ++```text +ΓööΓöÇΓöÇΓöÇbuild + ΓööΓöÇΓöÇΓöÇappPackage + Γö£ΓöÇΓöÇΓöÇappPackage.{env}.zip - Zipped app package of remote Teams app + Γö£ΓöÇΓöÇΓöÇappPackage.local.zip - Zipped app package of local Teams app + Γö£ΓöÇΓöÇΓöÇmanifest.{env}.json - Previewed manifest of remote Teams app + ΓööΓöÇΓöÇΓöÇmanifest.local.json - Previewed manifest of local Teams app +``` ++You can preview manifest file in local and remote environments. ++* [Preview manifest file in local environment](#preview-manifest-file-in-local-environment) +* [Preview manifest file in remote environment](#preview-manifest-file-in-remote-environment) + +### Preview manifest file in local environment ++To preview manifest file in local environment, you can press **F5** to run local debug. It generates default local settings for you, then the app package and preview manifest builds under `build/appPackage` folder. ++You can also preview local manifest file by following the steps: ++1. Select **Preview** in the codelens of `manifest.template.json` file and select **local**. +2. Select **Preview manifest file** on the menu bar of `manifest.template.json` file. +3. Select **Zip Teams metadata package** in Treeview and select **local**. ++The preview local appears as shown in the image: +++### Preview manifest file in remote environment ++**To preview manifest file in remote environment** ++* Select **Provision in the cloud** under **DEVELOPMENT** in Teams Toolkit extension or +* Trigger **Teams: Provision in the cloud** from command palette. + +It generates configuration for remote Teams app, and builds package and preview manifest under `build/appPackage` folder. ++You can also preview manifest file in remote environment by following steps: ++1. Select **Preview** in the codelens of `manifest.template.json` file. +2. Select **Preview manifest file** on the menu bar of `manifest.template.json` file. +3. Select **Zip Teams metadata package** in Treeview. +4. Select your environment. ++> [!NOTE] +> If there are more than one environment, you need to select the environment you want to preview as shown in the image: +++## Sync local changes to Dev Portal ++After previewing the manifest file, you can sync your local changes to Dev Portal by the following ways: ++1. Deploy Teams app manifest ++ You can deploy Teams app manifest in any of the following ways: ++ * Go to `manifest.template.json` file, and right-click to select `Deploy Teams app manifest` from context menu ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/deploy-manifest.png" alt-text="Deploy manifest"::: ++ * Trigger `Teams: Deploy Teams app manifest` from command palette ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/deploy-command.png" alt-text="Deploy from command palette"::: ++2. Update to Teams platform ++ You can update to Teams platform in any of the following ways: ++ * Select **Update to Teams platform** on the upper left-corner of `manifest.{env}.json` ++ * Trigger **Teams: Update manifest to Teams platform** on the menu bar of `manifest.{env}.json` ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/update-to-teams.png" alt-text="Update to teams"::: ++You can also trigger **Teams: Update manifest to Teams platform** from the command palette: +++> [!NOTE] +> Trigger from editor codelens or menu bar updates current manifest file to Teams platform. Trigger from command palette requires selecting target environment. ++ CLI command: ++``` bash + teamsfx deploy manifest --include-app-manifest yes +``` ++++> [!NOTE] +> The change updates to Dev Portal. Any manual updates in Dev Portal are overwritten. ++If the manifest file is outdated due to configuration file change or template change, select any one of the following action: ++* **Preview only**: Local manifest file is overwritten according to current configuration +* **Preview and update**: Local manifest file is overwritten according to current configuration and also updated to Teams platform +* **Cancel**: No action is taken ++++## Customize Teams app manifest ++Teams Toolkit consists of the following manifest template files under `manifest.template.json` folder across local and remote environments: ++* `manifest.template.json` +* `templates/appPackage` +++During the local debug or provision, Teams Toolkit loads manifest from `manifest.template.json`, with the configurations from `state.{env}.json`, `config.{env}.json`, and creates Teams app in [Dev Portal](https://dev.teams.microsoft.com/apps). ++## Supported placeholders in manifest.template.json ++The following list provides supported placeholders in `manifest.template.json`: ++* `{{state.xx}}` is pre-defined placeholder and it's value is resolved by Teams Toolkit, defined in `state.{env}.json`. Ensure not to modify the values in `state.{env}.json` +* `{{config.manifest.xx}}` is a customized placeholder and it's value is resolved from `config.{env}.json` ++**To add customized parameter** ++1. Add customized parameter as follows:</br> + a. Add a placeholder in `manifest.template.json` with pattern `{{config.manifest.xx}}`.</br> + b. Add a config value in `config.{env}.json`. ++ ```json + { + "manifest": { + "KEY": "VALUE" + } + } + ``` ++2. You can navigate to configuration file by selecting any one of the config placeholder **Go to config file** or **View the state file** in `manifest.template.json`. ++### Validate manifest ++During operations such as, **Zip Teams metadata package**, Teams Toolkit validates the manifest against its schema. The following list provides different ways to validate manifest: ++* In VSC, trigger `Teams: Validate manifest file` from command palette: ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/validate.png" alt-text="Validate file"::: ++* In CLI, use command: ++ ``` bash + teamsfx validate --env local + teamsfx validate --env dev + ``` ++++## Codelenses and hovers ++In `manifest.template.json`, you can navigate to codelens to preview the values for `local` and `dev` environment. +++> [!NOTE] +> Provision the environment or execute local debug to generate values for placeholders. ++You can navigate to state file or configuration file by selecting the codelens, which provides a drop-down list with all the environment names. After selecting one environment, the corresponding state file or configuration file opens. +++To preview values for all the environments, you can hover over the placeholder. It shows a list with environment names and corresponding values. If you haven't provisioned the environment or executed the local debug, select `Trigger Teams: Provision in the cloud command to see placeholder value` or `Trigger local debug to see placeholder value`. ++++## See also ++* [Manage multiple environments](TeamsFx-multi-env.md) +* [Reference: Manifest schema for Microsoft Teams](../resources/schem) +* [Public developer preview for Microsoft Teams](../resources/dev-preview/developer-preview-intro.md) |
| platform | Add API Connection | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/add-API-connection.md | + + Title: Connect to existing APIs ++description: Describes connection to existing APIs ++ms.localizationpriority: medium + Last updated : 05/20/2022+++# Add API connection to Teams app ++Teams Toolkit helps you to access existing APIs for building Teams applications. These APIs are developed by your organization or third-party. ++## Advantage ++Teams Toolkit helps you bootstrap sample code to access the APIs if you don't have language appropriate SDKs to access these APIs. ++## Connect to the API ++When you use Teams Toolkit to connect to an existing API, Teams Toolkit performs the following function: ++* Generate sample code under `./bot` or `./api` folder +* Add a reference to the `@microsoft/teamsfx` package to `package.json` +* Add application settings for your API in `.env.teamsfx.local` that configures local debugging ++### Connect to API in Visual Studio Code ++* You can add API connection using Teams Toolkit in Visual Studio Code: ++ 1. Open Microsoft Visual Studio Code. + 2. Select Teams Toolkit :::image type="icon" source="../assets/images/teams-toolkit-v2/add-API/api-add-icon.png" alt-text="api icon"::: from the left navigation bar. + 3. Select **Add features** under **DEVELOPMENT**: ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-add-features.png" alt-text="api add features"::: ++ * You can also open the command palette and enter **Teams: Add cloud resources**. ++ 4. From the pop-up, select the **API Connection** you want to add to your Teams app project: ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-select-features.png" alt-text="api select features"::: ++ 5. Select **OK**. ++ 6. Enter endpoint for the API. It's added to the project's local application settings and it's the base URL for API requests. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-endpoint.png" alt-text="api endpoint"::: ++ > [!NOTE] + > Ensure the endpoint is a valid http(s) URL. ++ 7. Select the component that accesses the API. ++ 8. Select **OK**. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-invoke.png" alt-text="api invoke"::: ++ 9. Enter an alias for the API. The alias generates an application setting name for the API that is added to the project's local application setting. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-alias.png" alt-text="api alias"::: ++ 10. Select required authentication for the API request from the **API authentication type**. It generates appropriate sample code and adds corresponding local application settings based on your selection. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-API/api-auth.png" alt-text="api auth"::: ++ > [!NOTE] + > Based on the authentication type selected, additional configuration is needed. ++### API connection in TeamsFx CLI ++The base command of this feature is `teamsfx add api-connection [authentication type]`. The following table provides list of different authentication types and their corresponding sample commands: ++ > [!Tip] + > You can use `teamsfx add api-connection [authentication type] -h` to get help document. ++ |**Authentication type**|**Sample command**| + |--|| + |Basic|teamsfx add api-connection basic --endpoint <https://example.com> --component bot --alias example --user-name exampleuser --interactive false| + |API Key|teamsfx add api-connection apikey --endpoint <https://example.com> --component bot --alias example --key-location header --key-name example-key-name --interactive false| + |Azure AD|teamsfx add api-connection aad --endpoint <https://example.com> --component bot --alias example --app-type custom --tenant-id your_tenant_id --app-id your_app_id --interactive false| + |Certificate|teamsfx add api-connection cert --endpoint <https://example.com> --component bot --alias example --interactive false| + |Custom|teamsfx add api-connection custom --endpoint <https://example.com> --component bot --alias example --interactive false| ++## Understand Toolkit updates to your project ++ Teams Toolkit modifies `bot` or `api` folder based on your selections: ++1. Generate `{your_api_alias}.js/ts` file. The file initializes an API client for your API and exports the API client. ++2. Add `@microsoft/teamsfx` package to `package.json`. The package provides support for the common API authentication methods. ++3. Add environment variables to `.env.teamsfx.local`. They are the configurations for the selected authentication type. The generated code reads values from the environment variables. ++## Test API connection in local environment ++The following steps help to test the API connection in the Teams Toolkit local environment: ++ 1. **Run npm install** ++ Run `npm install` under `bot` or `api` folder to install added packages. ++ 2. **Add API credentials to the local application settings** ++ Teams Toolkit does't ask for credentials but it leaves placeholders in the local application settings file. Replace the placeholders with the appropriate credentials to access the API. The local application settings file is the `.env.teamsfx.local` file in the `bot` or `api` folder. ++ 3. **Use the API client to make API requests** ++ Import the API client from the source code that needs access to the API: ++ ```BASH + import { yourApiClient } from '{relative path to the generated file}' + ``` ++ 4. **Generate http(s) requests to target API (with Axios)** ++ The generated API client is an Axios API client. Use the Axios client to make requests to the API. ++ > [!Note] + >[Axios](https://www.npmjs.com/package/axios) is a popular nodejs package that helps you with http(s) requests. For more information on how to make http(s) requests, see [Axios example documentation](https://axios-http.com/docs/example) to learn how to make http(s). ++## Deploy your application to Azure ++To deploy your application to Azure, you need to add the authentication to the application settings for the appropriate environment. For example, your API might have different credentials for `dev` and `prod`. Based on environment needs, configure Teams Toolkit. ++Teams Toolkit configures your local environment. The bootstrapped sample code contains comments that tell you what app settings you need to configure. For more information on application settings, see [Add app settings](https://github.com/OfficeDev/TeamsFx/wiki/%5BDocument%5D-Add-app-settings). ++## Advanced scenarios ++ The following section explains you advanced scenarios: ++<br> ++<details> +<summary><b>Custom authentication provider</b></summary> ++Besides the authentication provider included in `@microsoft/teamsfx` package, you can also implement customized authentication provider that implements `AuthProvider` interface and use it in `createApiClient(..)` function: ++```Bash +import { AuthProvider } from '@microsoft/teamsfx' ++class CustomAuthProvider implements AuthProvider { + constructor() { + // You can add necessary parameters for your customized logic in constructor + } ++ AddAuthenticationInfo: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig> = async ( + config + ) => { + /* + * The config parameter contains all the request information and can be updated to include extra authentication info. + * Refer https://axios-http.com/docs/req_config for detailed document for the config object. + * + * Add your customized logic that returns updated config + */ + }; +} +``` +</details> +<details> +<summary><b>Connect to APIs for Azure AD permissions</b></summary> +Azure AD authenticates some services. The following list helps to access these services for configuring API permissions. ++* [Use Access Control Lists (ACLs)](#access-control-lists-acls) +* [Use Azure AD application permissions](#azure-ad-application-permissions) ++Obtaining a token with the right resource scopes for your API depends on the implementation of the API. ++You can follow the steps to access these APIs while using: ++#### Access Control Lists (ACLs) ++ 1. Start local debug on cloud environment for your project. It creates an Azure AD Application Registration your Teams application. + + 2. Open `.fx/states/state.{env}.json`, and note the value of `clientId` under `fx-resource-aad-app-for-teams` property. ++ 3. Provide the client ID to the API provider to configure ACLs on the API service. ++#### Azure AD application permissions ++ 1. Open `templates/appPackage/aad.template.json` and add following content to `requiredResourceAccess` property: ++```JSON + { + "resourceAppId": "The AAD App Id for the service providing the API you are connecting to", + "resourceAccess": [ + { + "id": "Target API's application permission Id", + "type": "Role" + } + ] + } +``` ++ 2. Start local debug on cloud environment for your project. It creates an Azure AD Application Registration your Teams application. ++ 3. Open `.fx/states/state.{env}.json` and note the value of `clientId` under `fx-resource-aad-app-for-teams` property. It's the application client ID. ++ 4. Grant admin consent for the required application permission, for more information, see [grant admin consent](/azure/active-directory/manage-apps/grant-admin-consent#grant-admin-consent-in-app-registrations). ++ > [!NOTE] + > For application permission use your client ID. +</details> ++## See also ++* [Publish Teams apps using Teams Toolkit](publish.md) |
| platform | Add Capability | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/add-capability.md | -# Add capabilities to your Teams apps +# Add capabilities to Teams apps -During app development, you can create a new Teams app with Teams app capability. The following table lists the Teams app capabilities: +Add capability in Teams Toolkit helps you to add additional capability to your existing Teams app.The following table lists the Teams app capabilities: |**Capability**|**Description**| |--|-|-| Tabs | Tabs are simple HTML tags that point to domains declared in the app manifest. You can add tabs as a part of channel inside a team, group chat, or personal app for an individual user| -| Bots | Bots help to interact with your web service through text, interactive cards, and task modules| -| Message extensions | Message extensions help to interact with your web service through buttons and forms in the Microsoft Teams client| +| Tabs | Tabs are simple HTML tags that refer to domains declared in the app manifest. You can add tabs as a part of channel inside a team, group chat, or personal app for an individual user.| +| Bots | Bots help to interact with your web service through text, interactive cards, and task modules.| +| Message extensions | Message extensions help to interact with your web service through buttons and forms in the Microsoft Teams client.| -## Prerequisite +## Advantages -* Install the [latest version of Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension). +The following list provides advantages to add more capabilities in TeamsFx: -> [!TIP] -> Ensure you have Teams app project opened in VS code. +* Provides convenience +* Adds more function to your app by automatically adding source codes using Teams Toolkit ## Limitations -The limitations to TeamsFx while adding more capabilities are as follows: +The following list provides limitations to add more capabilities in TeamsFx: * You can add tabs up to 16 instances-* You can add bot and message extension for one instance each +* You can add a bot and message extension for one instance each ## Add capabilities -> [!Note] -> You need to perform the provision for each environment, after you successfully add capabilities to your Teams app. -* You can add capabilities using Teams Toolkit in Visual Studio Code - 1. Open **Microsoft Visual Studio Code** - 1. Select **Teams Toolkit** from left panel - 1. Select **Add capabilities** +**You can add capabilities by the following methods:** - :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add capabilities.png" alt-text="capabilities"::: +* To add capabilities by using Teams Toolkit in Visual Studio Code +* To add capabilities by using command palette -* You can also open the command palette and enter Teams: Add Capabilities: + > [!Note] + > You need to provision for each environment, after you have successfully added the capabilities in your Teams app. - :::image type="content" source="../assets/images/teams-toolkit-v2/manual/tree view capabilities.png" alt-text="Alternate capabilities"::: +* **To add capabilities by using Teams Toolkit in Visual Studio Code:** + 1. Open **Visual Studio Code**. + 1. Select **Teams Toolkit** from left panel. + 1. Select **Add features** under **DEVELOPMENT**. - 1. From the pop-up, select the capabilities to include in your project: + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/select-feature123.png" alt-text="updated one" border="true"::: - :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/select capabilities.png" alt-text="select"::: +* **To add capabilities by using command palette:** - 2. Select **OK** + 1. Open **command palette**. + 1. Enter **Teams:Add features**. + 1. Press **Enter**. -The selected capabilities are successfully added to your project. The Teams Toolkit generate source code for newly added capabilities + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/Teams-add-features.png" alt-text="team feature" border="true"::: -## Add capabilities using TeamsFx CLI in command window + 1. From the pop-up, select the capability to add in your project. -1. Change directory to your **project directory** -1. Execute the following command to add different capabilities to your project: + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/notification-add-capabilities.png" alt-text="notification" border="true"::: - |Capability and Scenario| Command| - |--|-| - |To add tab|`teamsfx capability add tab`| - |To add bot|`teamsfx capability add bot`| - |To add message extension|`teamsfx capability add messaging-extension`| +## Add capabilities using TeamsFx CLI -## Supported capabilities +* Change directory to your **project directory** +* The following table lists the capabilities and required commands: -Apart from the capabilities your Teams app already have, you can choose to add different capabilities to your Teams app. The following table provides the different Teams app capabilities: + |Capability and Scenario| Command| + |--|-| + |To add notification bot |`teamsfx add notification `| + |To add command bot |`teamsfx add command-and-response `| + |To add sso-enabled tab |`teamsfx add sso-tab`| + |To add tab |`teamsfx add tab`| + |To add bot |`teamsfx add bot`| + |To add message extension |`teamsfx add message extension`| ++## Available capabilities to add for different Teams project ++You can choose to add different capabilities based on project you have created in Teams app. +The following table lists the available capabilities to add in your project: |Existing capabilities|Other supported capabilities| |--|--|-|Tabs with SPFx|None| -|Tabs with Azure|Bot and message extension| -|Bot|Tabs| -|Message extension|Tabs and bot| -|Tabs and bot|Tabs and message extension| -|Tabs and message extension|Tabs and bot| -|Tabs, bot, and message extension|Tabs| -|Tabs |Bot and message extension| +|SPFx tab |None| +|SSO-enabled tab |SSO-enabled tab, notification bot, command bot, bot, message extension| +|Notification bot |SSO-enabled tab, tab| +|Command bot |SSO-enabled tab, tab| +|Tab |Tab, notification bot, command bot, bot, message extension| +|Bot |Message extension, SSO-enabled tab, tab| +|Message extension |Bot, SSO-enabled tab, tab | ## Add bot, tab and message extension After adding tab, the changes in your project are as follows: * The files under `templates/azure/teamsfx` will be updated, and `templates/azure/provision/xxx`.bicep file will be regenerated * The file under `.fx/config` are regenerated, which ensures your project is set with right configurations for newly added capability +## Step-by-step guide ++* Follow the [step-by-step](../sbs-gs-commandbot.yml) guide to build command bot in Microsoft Teams ++* Follow the [step-by-step](../sbs-gs-notificationbot.yml) guide to build notification bot in Microsoft Teams. ## See also |
| platform | Add Resource | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/add-resource.md | Title: Add Resources to Your Teams apps + Title: Add Resources to Teams apps description: Describes Add Resources of Teams Toolkit -# Add cloud resources to your Teams app +# Add cloud resources to Teams app -TeamsFx helps to provision cloud resources for your application hosting. You can also optionally add cloud resources that fit your development needs. +TeamsFx helps to provision the cloud resources for your application hosting. You can add the cloud resources optionally, that fit your development needs. -## Prerequisite +## Advantages -[Install Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) version v3.0.0+. +The following list provides advantages to add more cloud resources in TeamsFx: -> [!TIP] -> Ensure you have Teams app project in Visual Studio Code. +* Provides convenience +* Autogenerates all configuration files and connect to Teams app by using Teams Toolkit -## Add cloud resources using Teams Toolkit +## Limitation ++If you have created SPFx based tab project, you can't add Azure cloud resources. ++## Add cloud resources ++**You can add cloud resources by the following methods:** -> [!IMPORTANT] -> You need to provision each environment after you add a resource. +* To add cloud resources by using Teams Toolkit in Visual Studio Code +* To add cloud resources by using command palette -1. Open **Microsoft Visual Studio Code**. -1. Select **Teams Toolkit** from left pane. -1. In the Teams Toolkit side bar panel, select **Add cloud resources**: + > [!NOTE] + > You need to provision for each environment, after you have successfully added the resource in your Teams app. + +* **To add cloud resources by using Teams Toolkit in Visual Studio Code:** - :::image type="content" source="../assets/images/teams-toolkit-v2/manual/add cloudresources.png" alt-text="Add resources"::: + 1. Open **Visual Studio Code**. + 1. Select **Teams Toolkit** from left panel. + 1. Select **Add features** under **DEVELOPMENT**. - You can also open the command palette and enter **Teams: Add cloud resources**: + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/cloud/select-feature-updated.png" alt-text="add feature" border="true"::: - :::image type="content" source="../assets/images/teams-toolkit-v2/manual/addcloud.png" alt-text="add cloud resources"::: +* **To add cloud resources by using command palette:** -1. From the pop-up, select the cloud resources you want to add to your Teams app project: + 1. Open **command palette**. + 1. Enter **Teams:Add features**. + 1. Press **Enter**. - :::image type="content" source="../assets/images/teams-toolkit-v2/manual/addresources.png" alt-text="add"::: + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/cloud/Teams-add-features.png" alt-text="cloud" border="true"::: -1. Select **OK**. + 1. From the pop-up, select the cloud resources to add in your project. -The selected resources are successfully added to your project. + :::image type="content" source="~/assets/images/teams-toolkit-v2/manual/cloud/updated-final-cloud.png" alt-text="final" border="true"::: -## Add cloud resources using TeamsFx CLI in command window +## Add cloud resources using TeamsFx CLI -1. Change directory to your **project directory**. -1. Execute the following command to add different resources in your project: +* Change directory to your **project directory**. +* The following table lists the capabilities and required commands: -|Cloud Resource|Command| -||-| -| Azure function|`teamsfx resource add azure-function --function-name your-func-name`| -| Azure SQL database|`teamsfx resource add --function-name your-func-name`| -| Azure API management|`teamsfx resource add azure-apim`| -| Azure Key Vault|`teamsfx resource add azure-keyvault`| + |Cloud Resource|Command| + ||-| + | Azure function|`teamsfx add azure-function`| + | Azure SQL database|`teamsfx add azure-sql`| + | Azure API management|`teamsfx add azure-apim`| + | Azure Key Vault|`teamsfx add azure-keyvault`| ## Types of cloud resources -TeamsFx integrates with Azure services for the following scenarios: +In the following scenarios, TeamsFx integrates with Azure - [Azure functions](/azure/azure-functions/functions-overview): A serverless solution to meet your on-demand requirements, such as creating web APIs for your Teams applications backend. - [Azure SQL database](/azure/azure-sql/database/sql-database-paas-overview): A platform as a service (PaaS) database engine to serve as your Teams applications data store.-- [Azure API management](deploy.md): An API gateway that can be used to administer APIs created for Teams applications and publish them to consume on other applications, such as Power apps.+- [Azure API management](deploy.md): An API gateway can be used to administer APIs created for Teams applications and publish them to consume on other applications, such as Power apps. - [Azure Key Vault](/azure/key-vault/general/overview): Safeguard cryptographic keys and other secrets used by cloud apps and services. ## Add Cloud resources -After adding any resource, the changes in your project are as follows: +The following changes appear after adding resources in your project: -- New parameters may be added to azure.parameter.{env}.json to provide required information for provision.-- New content is appended to ARM template under `templates/azure` folder except the files under `templates/azure/teamsfx` folder to create the added Azure resources.+- New parameters added to azure.parameter.{env}.json to provide required information for provision. +- New content is included to ARM template under `templates/azure`, except the files are in `templates/azure/teamsfx` folder for added the Azure resources. - The files under `templates/azure/teamsfx` folder are regenerated to ensure TeamsFx required configuration are up to date for added Azure resources.-- `.fx/projectSettings.json` is updated to track the resources present in your project.+- `.fx/projectSettings.json` is updated to track the available resources in your project. -After adding resources, the additional changes in your project are as follows: +The following additional changes appear after adding resources in your project: |Resources|Changes|Description| |||--| |Azure functions|An Azure functions template code is added into a subfolder with path `yourProjectFolder/api`</br></br>`launch.json` and `task.json` updated under `.visual studio code` folder.| Includes a hello world http trigger template into your project.</br></br> Includes necessary scripts for Visual Studio Code to be executed when you want to debug your application locally.| |Azure API management|An open API specification file added into a subfolder with path `yourProjectFolder/openapi`|Defines your API after publishing, it's the API specification file.| -## Limitation --You can't add resources if you've created SPFx based tab project. - ## See also -[Provision cloud resources](provision.md) +* [Provision cloud resources](provision.md) +* [Create a new Teams app](create-new-project.md) +* [Add capabilities to Teams apps](add-capability.md) +* [Deploy to the cloud](deploy.md) |
| platform | Add Single Sign On | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/add-single-sign-on.md | + + Title: Add single sign-on to your Teams apps ++description: Describes Add single sign on of Teams Toolkit ++ms.localizationpriority: medium + Last updated : 05/20/2022+++# Add single sign-on to Teams app ++Microsoft Teams provides single sign-on function for application to obtain signed-in Teams user token to access Microsoft Graph and other APIs. Teams Toolkit facilitates the interaction by abstracting some of the Azure AD flows and integrations behind some simple APIs. This enables you to add single sign-on (SSO) features easily to your Teams application. ++For applications that interact with the user in a chat, a Team, or a channel, SSO manifests as an Adaptive Card which the user can interact with to invoke the Azure AD consent flow. ++## Enable SSO support ++Teams Toolkit helps you to add SSO to the following Teams capabilities: ++* Tab +* Bot +* Notification bot: restify server +* Command bot ++### Add SSO using Visual Studio Code ++The following steps helps you to add SSO using Teams Toolkit in Visual Studio Code ++1. Open **Microsoft Visual Studio Code**. +2. Select Teams Toolkit :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso/teams-toolkit-sidebar-icon.png" alt-text="sso add sidebar"::: from left navigation bar. +3. Select **Add features** under **DEVELOPMENT**. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso/sso-add features.png" alt-text="sso add features"::: ++ * You can also open command palette and select **Teams: Add features** ++4. Select **Single Sign-On**. ++ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso/sso-select features.png" alt-text="sso select"::: ++### Add SSO using TeamsFx CLI ++You can run `teamsfx add sso` command in your **project root directory** ++> [!Note] +> The feature enables SSO for all existing applicable capabilities. Follow the same steps to enable SSO if you add capability later to the project. ++## Customize your project using Teams Toolkit ++The following table lists the changes Teams Toolkit makes to your project: ++ |**Type**|**File**|**Purpose**| + |--|--|--| + |Create|`aad.template.json` under `template/appPackage`|Azure AD application manifest represents your Azure AD app. `template/appPackage` helps to register an Azure AD app during local debug or provision stage.| + |Modify|`manifest.template.json` under `template/appPackage`|A `webApplicationInfo` object is added into your Teams app manifest template. Teams requires this field to enable SSO. The change is in effect when you trigger local debug or provision.| + |Create|`auth/tab`|Reference code, auth redirect pages and a `README.md` file is generated in this path for a tab project.| + |Create|`auth/bot`|Reference code, auth redirect pages and a `README.md` file is generated in this path for a bot project.| ++> [!Note] +> By adding SSO, Teams Toolkit doesn't change anything in the cloud until you trigger local debug. Update your code to ensure that SSO is working in the project. ++## Update your application to use SSO ++The following steps helps you to enable SSO in your application. ++> [!NOTE] +> These changes are based on the templates we scaffold. +++<br> +<br><details> +<summary><b>Tab project +</b></summary> ++1. Copy `auth-start.html` and `auth-end.htm`** in `auth/public` folder to `tabs/public/`. Teams Toolkit registers these two endpoints in Azure AD for Azure AD's redirect flow. ++2. Copy `sso` folder under `auth/tab` to `tabs/src/sso/`. ++ * `InitTeamsFx`: The file implements a function that initializes TeamsFx SDK and opens `GetUserProfile` component after SDK is initialized ++ * `GetUserProfile`: The file implements a function that calls Microsoft Graph API to get user info ++3. Execute `npm install @microsoft/teamsfx-react` under `tabs/`. ++4. Add the following lines to `tabs/src/components/sample/Welcome.tsx` to import `InitTeamsFx`: ++ ```Bash ++ import { InitTeamsFx } from "../../sso/InitTeamsFx"; ++ ``` ++5. Replace the following line: `<AddSSO />` with `<InitTeamsFx />` to replace the `AddSso` component with `InitTeamsFx` component. ++</details> +<details> +<summary><b>Bot project +</b></summary> ++1. Copy `auth/bot/public` folder to `bot/src`. The two folders contain HTML pages used for auth redirect, you need to modify `bot/src/index` file to add routing to these pages. ++2. Copy `auth/bot/sso` folder to `bot/src`. The two folders contain three files as reference for SSO implementation: ++ * `showUserInfo`: It implements a function to get user info with SSO token. You can follow this to create your own method that requires SSO token. ++ * `ssoDialog`: It creates a [ComponentDialog](/javascript/api/botbuilder-dialogs/componentdialog?view=botbuilder-ts-latest&preserve-view=true) that is used for SSO. ++ * `teamsSsoBot`: It creates a [TeamsActivityHandler](/javascript/api/botbuilder/teamsactivityhandler?view=botbuilder-ts-latest&preserve-view=true) with `ssoDialog` and add `showUserInfo` as a command that can be triggered. ++3. Follow the code sample and register your own command with `addCommand` in this file (optional). ++4. Execute `npm install isomorphic-fetch` under `bot/`. ++5. Execute `npm install copyfiles` under `bot/` and replace following line in package.json: + + ```JSON ++ "build": "tsc --build", ++ ``` ++ with ++ ```JSON ++ "build": "tsc --build && copyfiles public/*.html lib/", ++ ``` ++ The HTML pages used for auth redirect are copied while building this bot project. ++6. After you add the following files, you need to create a new `teamsSsoBot` instance in `bot/src/index` file. Replace the following code: ++ ```Bash + + // Process Teams activity with Bot Framework. + server.post("/api/messages", async (req, res) => { + await commandBot.requestHandler(req, res); + }); ++ ``` ++ with ++ ```Bash ++ const handler = new TeamsSsoBot(); + // Process Teams activity with Bot Framework. + server.post("/api/messages", async (req, res) => { + await commandBot.requestHandler(req, res, async (context)=> { + await handler.run(context); + }); + }); ++ ``` ++7. Add the HTML routes in the `bot/src/index` file: ++ ```Bash ++ server.get( + "/auth-*.html", + restify.plugins.serveStatic({ + directory: path.join(__dirname, "public"), + }) + ); ++ ``` ++8. Add the following lines to `bot/src/index` to import `teamsSsoBot` and `path`: ++ ```Bash ++ // For ts: + import { TeamsSsoBot } from "./sso/teamsSsoBot"; + const path = require("path"); ++ // For js: + const { TeamsSsoBot } = require("./sso/teamsSsoBot"); + const path = require("path"); ++ ``` ++9. Register your command in the Teams app manifest. Open `templates/appPackage/manifest.template.json`, and add following lines under `command` in `commandLists` of your bot: ++ ```JSON ++ { + "title": "show", + "description": "Show user profile using Single Sign On feature" + } ++ ``` +</details> +<details> +<summary><b>Add a new command to the bot +</b></summary> ++> [!NOTE] +> Currently, these instructions applies to `command bot`. If you start with a `bot`, see [bot-sso sample](https://github.com/OfficeDev/TeamsFx-Samples/tree/v2/bot-sso). ++The following steps helps you to add a new command, after you add SSO in your project: ++1. Create a new file (`todo.ts` or `todo.js`) under `bot/src/` and add your own business logic to call Graph API: ++# [TypeScript](#tab/typescript) ++ ```typescript + // for TypeScript: +export async function showUserImage( + context: TurnContext, + ssoToken: string, + param: any[] +): Promise<DialogTurnResult> { + await context.sendActivity("Retrieving user photo from Microsoft Graph ..."); ++ // Init TeamsFx instance with SSO token + const teamsfx = new TeamsFx().setSsoToken(ssoToken); ++ // Update scope here. For example: Mail.Read, etc. + const graphClient = createMicrosoftGraphClient(teamsfx, param[0]); + + // You can add following code to get your photo: + // let photoUrl = ""; + // try { + // const photo = await graphClient.api("/me/photo/$value").get(); + // photoUrl = URL.createObjectURL(photo); + // } catch { + // // Could not fetch photo from user's profile, return empty string as placeholder. + // } + // if (photoUrl) { + // await context.sendActivity( + // `You can find your photo here: ${photoUrl}` + // ); + // } else { + // await context.sendActivity("Could not retrieve your photo from Microsoft Graph. Please make sure you have uploaded your photo."); + // } ++ return; +} + ``` ++# [JavaScript](#tab/javascript) ++ ```javaScript + // for JavaScript: +export async function showUserImage(context, ssoToken, param) { + await context.sendActivity("Retrieving user photo from Microsoft Graph ..."); ++ // Init TeamsFx instance with SSO token + const teamsfx = new TeamsFx().setSsoToken(ssoToken); ++ // Update scope here. For example: Mail.Read, etc. + const graphClient = createMicrosoftGraphClient(teamsfx, param[0]); + + // You can add following code to get your photo: + // let photoUrl = ""; + // try { + // const photo = await graphClient.api("/me/photo/$value").get(); + // photoUrl = URL.createObjectURL(photo); + // } catch { + // // Could not fetch photo from user's profile, return empty string as placeholder. + // } + // if (photoUrl) { + // await context.sendActivity( + // `You can find your photo here: ${photoUrl}` + // ); + // } else { + // await context.sendActivity("Could not retrieve your photo from Microsoft Graph. Please make sure you have uploaded your photo."); + // } ++ return; +} + ``` ++++2. Register a new command ++ * Add the following line for new command registration using `addCommand` in `teamsSsoBot`: ++ ```bash ++ this.dialog.addCommand("ShowUserProfile", "show", showUserInfo); ++ ``` ++ * Add following lines after the above line to register a new command `photo` and hook up with method `showUserImage` added above: ++ ```bash ++ // As shown here, you can add your own parameter into the `showUserImage` method + // You can also use regular expression for the command here + const scope = ["User.Read"]; + this.dialog.addCommand("ShowUserPhoto", new RegExp("photo\s*.*"), showUserImage, scope); ++ ``` ++3. Register your command in the Teams app manifest. Open `templates/appPackage/manifest.template.json`, and add following lines under `command` in `commandLists` of your bot: ++ ```JSON ++ { + "title": "photo", + "description": "Show user photo using Single Sign On feature" + } ++ ``` +</details> +<br> ++## Debug your application ++Press F5 to debug your application. Teams Toolkit uses the Azure AD manifest file to register an Azure AD application for SSO. For Teams Toolkit local debug functionalities, see [Debug your Teams app locally](debug-local.md). ++## Customize Azure AD application registration ++The [Azure AD app manifest](/azure/active-directory/develop/reference-app-manifest) allows you to customize various aspects of application registration. You can update the manifest as needed. If you need to include additional API permissions to access your desired APIs, see [API permissions to access your desired APIs](https://github.com/OfficeDev/TeamsFx/wiki/#customize-aad-manifest-template). +To view your Azure AD application in Azure Portal, see [View Azure AD application in Azure portal](https://github.com/OfficeDev/TeamsFx/wiki/Manage-AAD-application-in-Teams-Toolkit#How-to-view-the-AAD-app-on-the-Azure-portal). ++## SSO authentication concepts ++The following concepts helps you for SSO authentication: ++### Working of SSO in Teams ++Single sign-on (SSO) authentication in Microsoft Azure Active Directory (Azure AD) silently refreshes the authentication token to minimize the number of times users need to enter their sign-in credentials. If users agree to use your app, they don't have to provide consent again on another device as they're signed in automatically. ++Teams tabs and bots have similar flow for SSO support, for more information, see: ++1. [Single sign-on (SSO) authentication in Tabs](../tabs/how-to/authentication/auth-aad-sso.md) +2. [Single sign-on (SSO) authentication in Bots](../bots/how-to/authentication/auth-aad-sso-bots.md) ++### Simplified SSO with TeamsFx ++TeamsFx helps to reduce the developer tasks by using SSO and accessing cloud resources down to single line statements with zero configuration. ++With TeamsFx SDK, you can write user authentication code in a simplified way using Credentials: ++1. User identity in browser environment: `TeamsUserCredential` represents Teams current user's identity. +2. User identity in Node.js environment: `OnBehalfOfUserCredentail` uses On-Behalf-Of flow and SSO token. +3. Application Identity in Node.js environment: `AppCredential` represents the application identity. ++For more information about TeamsFx SDK, see: ++* [TeamsFx SDK](TeamsFx-SDK.md) or [API reference](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true) +* [Microsoft Teams Framework (TeamsFx) Sample Gallery](https://github.com/OfficeDev/TeamsFx-Samples/tree/v2) ++## See also ++* [Prepare accounts to build Teams apps](accounts.md) |
| platform | Create New Project | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/create-new-project.md | To create a new Teams app using Teams Toolkit, you can select from one of the fo 1. Open Visual Studio Code. 1. Select the Teams Toolkit :::image type="icon" source="../assets/images/teams-toolkit-v2/teams-toolkit-sidebar-icon.PNG" border="true"::: icon in the Visual Studio Code sidebar. 1. Select **Create a new Teams app**.-1. Select from the available capabilities tab, bot, message extension, or a tab using SharePoint Framework (SPFx). ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams-toolkit-sidebar.png" alt-text="Teams toolkit sidebar"::: ++1. You can select **Create a new Teams app** or **Start from a sample**. + + :::image type="content" source="../assets/images/teams-toolkit-v2/select-create-app.png" alt-text="Create an app"::: + +1. If you select **Create a new Teams app**, the following image displays with templates from three categories: Scenario-based Teams app, Basic Teams app, and Extended Teams apps across Microsoft 365: ++ :::image type="content" source="../assets/images/teams-toolkit-v2/teams-capabilities.png" alt-text="Capabilties for Teams app"::: + 1. Select at least one option to start creating the Teams app. + ### Create a new Teams app using view samples You can create a new app by exploring **View samples** and selecting an existing sample. The selected sample may already have some functionality, for example a to-do list with an Azure backend, or an integration with the Microsoft Graph Toolkit. 1. Open **Teams Toolkit** from Microsoft Visual Studio Code. 1. Select **DEVELOPMENT** section in Treeview.- 1. Select **View samples**. The sample gallery appears as shown in the following image: + 1. Select **View samples**. :::image type="content" source="../assets/images/teams-toolkit-v2/view-samples.png" alt-text="View samples"::: -You can explore and download samples and either run your app locally or remotely to preview in Teams web client. Follow the instructions for each sample, or select **View on GitHub** to open the sample within the `TeamsFx Samples repository` and browse the source code. + The sample gallery appears as shown in the following image: + + :::image type="content" source="../assets/images/teams-toolkit-v2/sample-gallery.png" alt-text="Sample gallery"::: ++ You can explore the sample gallery as follows: -For more information, see [Create a new Teams Tab app (React)](/microsoftteams/platform/sbs-gs-javascript?tabs=vscode%2Cvsc%2Cviscode%2Cvcode&tutorial-step=2). + 1. Select a sample to browse detailed information. + 1. Select **create** in information page of each sample to download it. + 1. Run your app locally or remotely to preview in Teams web client by following the instructions which automatically opens after you download the sample. + 1. If you donΓÇÖt want to download the samples, you can select **View on GitHub** to open the sample in the GitHub Samples repository and browse the source code. ## Step-by-step guides using Teams Toolkit For more information, see [Create a new Teams Tab app (React)](/microsoftteams/p * [Build a Teams app with JavaScript using React](../sbs-gs-javascript.yml) * [Build a Teams app with SPFx](../sbs-gs-spfx.yml) * [Build a Teams app with C# or .NET](../sbs-gs-csharp.yml)+* [Send notification to Teams](../sbs-gs-notificationbot.yml) +* [Build command bot](../sbs-gs-commandbot.yml) ## See also |
| platform | Debug Background Process | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/debug-background-process.md | Teams Toolkit checks the following prerequisites during the debug process: |Project type|Node.js LTS version| |-|--|- |Tab without Azure Functions | 10, 12, **14 (recommended)**, 16 | - |Tab with Azure Functions | 10, 12, **14 (recommended)**| - |Bot | 10, 12, **14 (recommended)**, 16| - |Message extension | 10, 12, **14 (recommended)**, 16 | + |Tab | 14, 16 (recommended) | + |SPFx Tab | 12, 14 (recommended)| + |Bot | 14, 16 (recommended)| + |Message extension | 14, 16 (recommended) | * Microsoft 365 account with valid credentials, the Teams toolkit prompts you to sign in to Microsoft 365 account, if you haven't signed in Teams Toolkit checks the following prerequisites during the debug process: * Ngrok binary version 2.3 is applicable for bot and message extension, if Ngrok isn't installed or the version doesn't match the requirement, the Teams toolkit installs Ngrok NPM package `ngrok@4.2.2` in `~/.fx/bin/ngrok`. The Ngrok binary is managed by Ngrok NPM package in `/.fx/bin/ngrok/node modules/ngrok/bin` -* Azure Functions Core Tools version 3, if Azure Functions Core Tools is'nt installed or the version doesn't match the requirement, the Teams Toolkit installs Azure Functions Core Tools NPM package, azure-functions-core-tools@3 for **Windows** and for **macOs** in `~/.fx/bin/func`. The Azure Functions Core Tools NPM package in `~/.fx/bin/func/node_modules/azure-functions-core-tools/bin` manages Azure Functions Core Tools binary. For Linux, the local debug terminates +* Azure Functions Core Tools version 4, if Azure Functions Core Tools is'nt installed or the version doesn't match the requirement, the Teams Toolkit installs Azure Functions Core Tools NPM package, azure-functions-core-tools@3 for **Windows** and for **macOs** in `~/.fx/bin/func`. The Azure Functions Core Tools NPM package in `~/.fx/bin/func/node_modules/azure-functions-core-tools/bin` manages Azure Functions Core Tools binary. For Linux, the local debug terminates * .NET Core SDK version applicable for Azure Functions, if .NET Core SDK is'nt installed or the version doesn't match the requirement, the Teams Toolkit installs .NET Core SDK for Windows and MacOS in `~/.fx/bin/dotnet`. For Linux, the local debug terminates |
| platform | Teams Toolkit Fundamentals | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/teams-toolkit-fundamentals.md | description: Overview of Teams Toolkit, Installation of Teams Toolkit, and Tour ms.localizationpriority: medium Previously updated : 11/29/2021 Last updated : 05/17/2022 # Teams Toolkit Overview -> [!NOTE] -> Currently, this feature is available in **public developer preview** only. Teams Toolkit for Microsoft Visual Studio Code helps you to create and deploy Teams apps with integrated identity, access to cloud storage, data from Microsoft Graph, and other services in Azure and Microsoft 365 with zero-configuration approach. For Teams app development, similar to Teams Toolkit for Visual Studio, you can use [CLI tool](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md), which consists of Toolkit `teamsfx`. Teams Toolkit lets you create, debug, and deploy your Teams app right from Visual Studio Code. App development with the toolkit has the advantages of: Teams Toolkit lets you create, debug, and deploy your Teams app right from Visua Teams Toolkit brings all tools needed for building a Teams app in one place. -For Teams app development, similar to Teams Toolkit for Visual Studio Code, you can use [CLI tool](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md), which consists of Toolkit `teamsfx`. - ## User journey of Teams Toolkit Teams Toolkit automates manual work and provides great integration of Teams and Azure resources. The following image shows Teams Toolkit user journey: The main milestones of this journey are: ## Install Teams Toolkit for Visual Studio Code 1. Open **Visual Studio Code.**-1. Select the Extensions view (**Ctrl+Shift+X** / **⌘⇧-X** or **View > Extensions**): +1. Select the Extensions view (**Ctrl+Shift+X** / **⌘⇧-X** or **View > Extensions**). :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/install toolkit-1.png" alt-text="install"::: -1. Enter **Teams Toolkit** in the search box: +1. Enter **Teams Toolkit** in the search box. - :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/install toolkit-2.png" alt-text="Toolkit"::: + :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/install-toolkit2.png" alt-text="Toolkit"::: -1. Select **Install**: +1. Select **Install**. - :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/install.png" alt-text="install toolkit"::: + :::image type="content" source="../assets/images/teams-toolkit-v2/teams toolkit fundamentals/install-toolkit.png" alt-text="install toolkit 4.0.0"::: > [!TIP] > You can install Teams Toolkit from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension). The main milestones of this journey are: After Toolkit installation, you'll see the Teams Toolkit UI as shown in following image: -You can select **Quick Start** to explore the Teams Toolkit, or select **Create a new Teams App** to create one Teams project. If you have a Teams project created by Teams Toolkit v2.+ opened in Visual Studio Code, you will see Teams Toolkit UI with all functionalities as shown in the following image: -You can select **Quick Start** to explore the Teams Toolkit, or select **Create a new Teams App** to create one Teams project. You can view a list of all Toolkit features when you create or open an existing project in Visual Studio Code sidebar. +You can select **Get Started** to explore the Teams Toolkit, or select **Create a new Teams App** to create one Teams project. If you have a Teams project created by Teams Toolkit opened in Visual Studio Code, you will see Teams Toolkit UI with all functionalities as shown in the following image: -Let's take a tour of the topics covered in this document: +Let's take a tour of the topics covered in this document. ## Accounts -To develop a Teams app, you need at least one Microsoft 365 account with a valid subscription. If you want to host your backend resources on Azure, an Azure account is also needed. Teams Toolkit supports integrated experience to sign in, provision and deployment for Azure resources. You can [create a free Azure account](https://azure.microsoft.com/free/) before you start. +To develop a Teams app, you need at least one Microsoft 365 account with a valid subscription. If you want to host your backend resources on Azure, an Azure account is also needed. Teams Toolkit supports integrated experience to sign-in, provision, and deployment for Azure resources. You can [create a free Azure account](https://azure.microsoft.com/free/) before you start. ## Environment Teams Toolkit helps you to create and manage multiple environments, provision, a It allows developers and project owner to invite other collaborators to the TeamsFx project to debug, provision, and deploy the same TeamsFx project. + ## Development Teams Toolkit helps you to create and customize your Teams app project that makes the Teams app development work simpler. ### Create a new Teams app -It helps you to start with Teams app development by creating new Teams project using Teams Toolkit either by using **Create new project** or **Create from samples**. --### Add capabilities --It helps to add other required Teams capabilities to Teams app during development process. +It helps you to start with Teams app development by creating new Teams project using Teams Toolkit either by using **Create new project** or **Start from a sample**. -### Add cloud resources +### Add Features -It helps you to optionally add cloud resources that fits your development needs. +It helps you to incrementally add additional Teams capabilities such as **Tab** or **Bot** or optionally add Azure resources such as **Azure SQL Database** or **Azure Key Vault**, which fits your development needs to your current Teams app. You can also add **Single Sign-on** or **CI/CD workflows** for your Teams app. ### Edit manifest file It integrates with Azure resource manager that enables you to provision Azure re After creating the app, you can distribute your app to different scope, such as individual, team, organization, or anyone. Publish to Teams helps you to publish your developed app. -### CI/CD guide --It helps to automate your development workflow while building Teams application. CI/CD guide provides tools and templates for you to get started while setting up CI or CD pipelines. - #### TeamsFx CLI It is a text-based command line interface that accelerates Teams application development and also enables CI/CD scenario where you can integrate CLI in scripts for automation. It helps you to reduce tasks of implementing identity and access to cloud resour ## Help and Feedback In this section, you can find the documentation and resources you need. You can select **Report issues on GitHub** in the Teams Toolkit to get **Quick support** from product expert. Browse the issue before you create a new one, or visit [StackOverflow tag `teams-toolkit`](https://stackoverflow.com/questions/tagged/teams-toolkit) to submit feedback.-+<!-- Let's explore Teams Toolkit features. -| Teams Toolkit Features | Includes... | What you can do | +| Teams Toolkit Features | Includes | What you can do | | | | | | **Accounts** | | | | | Microsoft 365 account | Use your Microsoft 365 account with a valid E5 subscription for building your app. | Let's explore Teams Toolkit features. | **Development** | | | | | Create a new Teams app | Use the toolkit wizard to prepare project scaffolding for app development. | | | View samples | Select any of Teams Toolkit's 12 sample apps. The toolkit downloads the app code from GitHub, and you can build the sample app. |-| | Add capabilities | Add other required Teams capabilities to Teams app during development process. | -| | Add cloud resources | Add optional cloud resources suitable for your app. | +| | Add Features | - Add other required Teams capabilities to Teams app during development process. </br> - Add optional cloud resources suitable for your app. | | | Edit manifest file | Edit the Teams app integration with Teams client. | | **Deployment** | | | | | Provision in the cloud | Allocate Azure resources for your application. Teams Toolkit is integrated with Azure Resource Manager. | Let's explore Teams Toolkit features. | | Deploy to the cloud | Deploy the source code to Azure. | | | Publish to Teams | Publish your developed app and distribute it to scopes, such as personal, team, channel, or organization. | | | Developer Portal for Teams | Use Developer Portal to configure and manage your Teams app. |-| | CI/CD guide | Automate your development workflow while building Teams application. | | **Help and Feedback** | | |-| | Quick Start | View the Teams Toolkit Quick Start help within Visual Studio Code. | +| | Quick start | View the Teams Toolkit Quick start help within Visual Studio Code. | +| | Tutorial | Select to access different tutorials. | | | Documentation | Select to access the Microsoft Teams Developer Documentation. | | | Report issues on GitHub | Select to access GitHub page and raise any issues. |-| +--> > [!TIP] > Browse existing issues before you create a new one, or visit [StackOverflow tag `teams-toolkit`](https://stackoverflow.com/questions/tagged/teams-toolkit) to submit feedback. |
| platform | Whats New | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/whats-new.md | keywords: teams what's new latest updates or developer preview and features # What's new for developers in Microsoft Teams -Discover Microsoft Teams platform features that are generally available (GA) and in developer preview. +Discover Microsoft Teams platform features that are generally available (GA) and in developer preview. You can now get latest Teams platform updates by subscribing to the RSS feed [](https://aka.ms/TeamsPlatformUpdates). For more information, see [configure RSS feed](#get-latest-updates). -> [!IMPORTANT] -> You can now get latest Teams platform updates by subscribing to the RSS feed [](https://aka.ms/TeamsPlatformUpdates). For more information, see [configure RSS feed](#get-latest-updates). +## Microsoft Build 2022 :::image type="icon" source="assets/images/bullhorn.png" border="false"::: +| Date | Feature | Find it here | +| | | | +| 05/24/2022| [*Developer preview*] <br> Enhanced collaboration with Live Share SDK | Build apps for Teams meetings > Enhanced collaboration with Live Share > [Overview](apps-in-teams-meetings/teams-live-share-overview.md) | +|05/24/2022| Submit your Outlook- and Office-enabled apps to the Teams store | Extend your app across Microsoft 365 > [Overview](m365-apps/overview.md) | +|05/24/2022| App guidance and what's new in TeamsJS version 2.0.0| Tools and SDKs > [Teams JavaScript client SDK](tabs/how-to/using-teams-client-sdk.md) | +| 05/24/2022 | Teams Toolkit version 4.0.0 for Visual Studio Code is now GA | Tools and SDKs > Teams Toolkit for Visual Studio Code > <br> ΓÇó [Teams Toolkit Overview](toolkit/teams-toolkit-fundamentals.md) <br> ΓÇó [Build command bot with JavaScript](toolkit/add-capability.md) <br> ΓÇó [Build notification bot with JavaScript](toolkit/add-capability.md) <br> ΓÇó [Preview and customize Teams app manifest](toolkit/TeamsFx-preview-and-customize-app-manifest.md) <br> ΓÇó [Connect to existing APIs](toolkit/add-API-connection.md) <br> ΓÇó [Add capabilities to your Teams apps](toolkit/add-capability.md) <br> ΓÇó [Add single sign-on experience](toolkit/add-single-sign-on.md) <br> ΓÇó [Add cloud resources to Teams app](toolkit/add-resource.md) | +| 05/24/2022 | Bots and Message extensions in GCC and GCCH | ΓÇó Plan your app > [Overview](concepts/app-fundamentals-overview.md#government-community-cloud) </br> ΓÇó Build bots > [Overview](bots/what-are-bots.md) </br> ΓÇó Build message extensions > [Overview](messaging-extensions/what-are-messaging-extensions.md) | ++<!-- ## Latest updates  | Date | Update | Find here | | | | |-|05/19/2022|Bots and Message extensions for GCC and GCCH| ΓÇó Build bots > [Overview](bots/what-are-bots.md) </br> ΓÇó Build message extensions > [Overview](messaging-extensions/what-are-messaging-extensions.md) | +|05/24/2022|Live Share SDK| Build apps for Teams meetings > Enhanced collaboration with Live Share > [Overview](apps-in-teams-meetings/teams-live-share-overview.md) | +|05/24/2022| Submit your Outlook- and Office-enabled apps to the Teams store | Extend your app across Microsoft 365 > [Overview](m365-apps/overview.md) | +|05/24/2022| App guidance and what's new in TeamsJS version 2.0.0| Tools and SDKs > [Teams JavaScript client SDK](tabs/how-to/using-teams-client-sdk.md) | +|05/19/2022|Bots and Message extensions in GCC and GCCH| ΓÇó Plan your app > [Overview](concepts/app-fundamentals-overview.md#government-community-cloud) </br> ΓÇó Build bots > [Overview](bots/what-are-bots.md) </br> ΓÇó Build message extensions > [Overview](messaging-extensions/what-are-messaging-extensions.md) | |04/28/2022| Common reasons for app validation failure | Distribute your app > Publish to the Teams store > [Common reasons for app validation failure](concepts/deploy-and-publish/appsource/common-reasons-for-app-validation-failure.md)| |04/20/2022 | Set up CI/CD pipelines | Tools and SDKs > Teams Toolkit for Visual Studio Code > [Set up CI/CD pipelines](toolkit/use-CICD-template.md)| |04/19/2022 | Upload your app in Microsoft Teams | Distribute your app > [Upload your app](concepts/deploy-and-publish/apps-upload.md)| Discover Microsoft Teams platform features that are generally available (GA) and |02/11/2022| Shared meeting stage| ΓÇó Build apps for Teams meetings > [Shared meeting stage](apps-in-teams-meetings/enable-and-configure-your-app-for-teams-meetings.md#shared-meeting-stage) </br> ΓÇó Build apps for Teams meetings > [Meeting apps API references](apps-in-teams-meetings/API-references.md) </br> ΓÇó App manifest > Public developer preview > [Developer preview manifest schema](resources/schem)| |02/08/2022| Introduced step-by-step guide to create Calling and Meeting bot| Build bots > Calls and meetings bots > Register calls and meetings bot > [Step-by-step guide to create Calling and Meeting bot](sbs-calling-and-meeting.yml) | |02/07/2022| Tools and SDKs |Teams Toolkit for Visual Studio Code > </br> ΓÇó Add capabilities to Teams app> [Add capabilities to your Teams apps](toolkit/add-capability.md) </br> ΓÇó Add cloud resources to Teams app> [Add cloud resources to your Teams app](toolkit/add-resource.md) |-|02/03/2022| Introduced app manifest version 1.12 | ΓÇó App manifest > [App manifest schema](resources/schem) | +|02/03/2022| Introduced app manifest version 1.12 | ΓÇó App manifest > [App manifest schema](resources/schem) |--> ## GA features Microsoft Teams platform features that are available to all app developers. | **Date** | **Update** | **Find here** | | -- | | -|-|05/19/2022|Bots and Message extensions for GCC and GCCH| ΓÇó Build bots > [Overview](bots/what-are-bots.md) </br> ΓÇó Build message extensions > [Overview](messaging-extensions/what-are-messaging-extensions.md) | +|05/24/2022| Additional tips for rapid approval to publish your app linked to a SaaS offer | Publish to the Teams store > Overview > [Additional tips for rapid approval to publish your app linked to a SaaS offer](~/concepts/deploy-and-publish/appsource/publish.md#additional-tips-for-rapid-approval-to-publish-your-app-linked-to-a-saas-offer) | +|05/24/2022| Submit your Outlook- and Office-enabled apps to the Teams store | Extend your app across Microsoft 365 > [Overview](m365-apps/overview.md) | +|05/24/2022| App guidance and what's new in TeamsJS version 2.0.0| Tools and SDKs > [Teams JavaScript client SDK](tabs/how-to/using-teams-client-sdk.md) | +| 05/24/2022 | Teams Toolkit version 4.0.0 for Visual Studio Code is now GA | Tools and SDKs > Teams Toolkit for Visual Studio Code > <br> ΓÇó [Teams Toolkit Overview](toolkit/teams-toolkit-fundamentals.md) <br> ΓÇó [Build command bot with JavaScript](toolkit/add-capability.md) <br> ΓÇó [Build notification bot with JavaScript](toolkit/add-capability.md) <br> ΓÇó [Preview and customize Teams app manifest](toolkit/TeamsFx-preview-and-customize-app-manifest.md) <br> ΓÇó [Connect to existing APIs](toolkit/add-API-connection.md) <br> ΓÇó [Add capabilities to your Teams apps](toolkit/add-capability.md) <br> ΓÇó [Add single sign-on experience](toolkit/add-single-sign-on.md) <br> ΓÇó [Add cloud resources to Teams app](toolkit/add-resource.md) | +|05/24/2022|Bots and Message extensions in GCC and GCCH| ΓÇó Plan your app > [Overview](concepts/app-fundamentals-overview.md#government-community-cloud) </br> ΓÇó Build bots > [Overview](bots/what-are-bots.md) </br> ΓÇó Build message extensions > [Overview](messaging-extensions/what-are-messaging-extensions.md) | |04/26/2022|Uninstall behavior for personal app with bot | Build bots > Bot conversations > [Uninstall behavior updates in personal apps with bots](bots/how-to/conversations/subscribe-to-conversation-events.md#uninstall-behavior-for-personal-app-with-bot)| |04/22/2022| Test preview for monetized apps | Monetize your app > [Test preview for monetized apps](concepts/deploy-and-publish/appsource/prepare/test-preview-for-monetized-apps.md) |04/22/2022| In-app purchase flow for monetization of apps | Monetize your app > [In-app purchases](concepts/deploy-and-publish/appsource/prepare/in-app-purchase-flow.md)+|04/28/2022| Common reasons for app validation failure | Distribute your app > Publish to the Teams store > [Common reasons for app validation failure](concepts/deploy-and-publish/appsource/common-reasons-for-app-validation-failure.md)| |04/20/2022 | Set up CI/CD pipelines | Tools and SDKs > Teams Toolkit for Visual Studio Code > [Set up CI/CD pipelines](toolkit/use-CICD-template.md)| |04/19/2022 | Upload your app in Microsoft Teams | Distribute your app > [Upload your app](concepts/deploy-and-publish/apps-upload.md)| |04/01/2022| Introduced step-by-step guide to create Teams conversational bot| Build bots > Bot conversations > Channel and group conversations > [Step-by-step guide to create Teams conversational bot](sbs-teams-conversation-bot.yml) | Developer preview is a public program that provides early access to unreleased T | **Date** | **Update** | **Find here** | | -- | | |-|04/06/2022| Share to Teams from personal app or tab | Integrate with Teams > Share to Teams > [Share to Teams from personal app or tab](concepts/build-and-test/share-to-teams-from-personal-app-or-tab.md) | -|02/07/2022| Tools and SDKs |Teams Toolkit for Visual Studio Code > </br> ΓÇó Add capabilities to Teams app> [Add capabilities to your Teams apps](toolkit/add-capability.md) </br> ΓÇó Add cloud resources to Teams app> [Add cloud resources to your Teams app](toolkit/add-resource.md) | -|02/02/2022| Introduced app manifest version 1.12 | App manifest > Public developer preview > [Manifest schema](resources/schem) | -|01/17/2022| People Picker in Adaptive cards for mobile | Build cards and task modules > Build cards > [People Picker in Adaptive Cards](task-modules-and-cards/cards/people-picker.md)| +|05/24/2022| Enhanced collaboration with Live Share SDK | Build apps for Teams meetings > Enhanced collaboration with Live Share > [Overview](apps-in-teams-meetings/teams-live-share-overview.md) | +| 04/06/2022 | Share to Teams from personal app or tab | Integrate with Teams > Share to Teams > [Share to Teams from personal app or tab](concepts/build-and-test/share-to-teams-from-personal-app-or-tab.md) | +| 02/07/2022 | Tools and SDKs |Teams Toolkit for Visual Studio Code > </br> ΓÇó Add capabilities to Teams app> [Add capabilities to your Teams apps](toolkit/add-capability.md) </br> ΓÇó Add cloud resources to Teams app> [Add cloud resources to your Teams app](toolkit/add-resource.md) | +| 02/03/2022 | Introduced app manifest version 1.12 | ΓÇó App manifest > [App manifest schema](resources/schem) | +|01/17/2022 | People Picker in Adaptive cards for mobile | Build cards and task modules > Build cards > [People Picker in Adaptive Cards](task-modules-and-cards/cards/people-picker.md)| |01/10/2022 | Teams Toolkit for Visual Studio Code | Tools and SDKs > Teams Toolkit for Visual Studio Code > [Teams Toolkit fundamentals](toolkit/teams-toolkit-fundamentals.md) |-|12/24/2021| Introduced step-by-step guide to grant Tab device permissions | App fundamentals > Device capabilities > [step-by-step guide to grant Tab device permissions](sbs-tab-device-permissions.yml) | -|11/15/2021| Personal tabs and message extensions run in Outlook and Office | [Extend Teams apps across Microsoft 365](~/m365-apps/overview.md) | -|10/28/2021|Bots can be enabled to receive all channel messages using resource-specific consent (RSC) | ΓÇó Build bots > Bot conversations > Messages in bot conversations > [Receive all messages with RSC](~/bots/how-to/conversations/channel-messages-with-rsc.md) </br> ΓÇó Build bots > Bot conversations > [bot conversation overview](~/bots/how-to/conversations/conversation-basics.md) </br> ΓÇó Build bots > Bot conversations > [channel and group conversations](~/bots/how-to/conversations/channel-and-group-conversations.md) </br> ΓÇó App manifest > Public developer preview > [developer preview manifest schema](~/resources/schem) | -|06/16/2021| Resource-specific consent for chats | ΓÇó Utilize Teams data with Microsoft Graph > [Resource-specific consent](graph-api/rsc/resource-specific-consent.md) </br> ΓÇó Test your app > Microsoft Graph > [Test resource-specific consent permissions in Teams](graph-api/rsc/test-resource-specific-consent.md)| +| 12/24/2021 | Introduced step-by-step guide to grant Tab device permissions | App fundamentals > Device capabilities > [step-by-step guide to grant Tab device permissions](sbs-tab-device-permissions.yml) | +| 11/15/2021 | Personal tabs and message extensions run in Outlook and Office | [Extend Teams apps across Microsoft 365](~/m365-apps/overview.md) | +| 10/28/2021 |Bots can be enabled to receive all channel messages using resource-specific consent (RSC) | ΓÇó Build bots > Bot conversations > Messages in bot conversations > [Receive all messages with RSC](~/bots/how-to/conversations/channel-messages-with-rsc.md) </br> ΓÇó Build bots > Bot conversations > [bot conversation overview](~/bots/how-to/conversations/conversation-basics.md) </br> ΓÇó Build bots > Bot conversations > [channel and group conversations](~/bots/how-to/conversations/channel-and-group-conversations.md) </br> ΓÇó App manifest > Public developer preview > [developer preview manifest schema](~/resources/schem) | +| 06/16/2021 | Resource-specific consent for chats | ΓÇó Utilize Teams data with Microsoft Graph > [Resource-specific consent](graph-api/rsc/resource-specific-consent.md) </br> ΓÇó Test your app > Microsoft Graph > [Test resource-specific consent permissions in Teams](graph-api/rsc/test-resource-specific-consent.md)| For more information, see [public developer preview for Teams](~/resources/dev-preview/developer-preview-intro.md). |