diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index 03394927ae9..dae72f4a9c9 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -12,97 +12,449 @@ A message extension allows the users to interact with your web service through b :::image type="content" border="false" source="../assets/images/get-started/get-started-me.png" alt-text="Screenshot shows you the conceptual message extension in Teams client."::: -In this tutorial, you'll learn to build a search-based message extension app, and the app allows users to search npm packages from the Node Package Manager (npm) directory. +Start Microsoft Teams app development with your first Teams app using JavaScript. -Get familiarized with search based message extension app in one of the following ways: +In this tutorial, you'll learn: -* **GitHub Codespaces**: The codespace instance allows you to experience a Teams app instantaneously. It opens Visual Studio Code (VS Code), where the Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) extension, the app source code, and all the dependencies are pre-packaged for you. -* **Step-by-step guide**: Allows you to set up your development environment and build a Teams app from start. +- [How to set up a new project with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit)](#create-your-message-extension-project-workspace) +- [How to build a message extension app](#build-and-run-your-first-message-extension-app) +- [How to deploy your app](#deploy-your-first-teams-app) -# [GitHub Codespaces](#tab/agentstoolkitcodespaces) +You'll see the following output after you complete this guide: -Before you create your codespace, ensure that you have the following prerequisites: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png" alt-text="Screenshot shows the final output of the message extension app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png"::: -* A GitHub account to create your codespace instance -* A [Microsoft 365 account](https://developer.microsoft.com/microsoft-365/dev-program) with custom app upload permission -* A [Microsoft 365 tenant](../concepts/build-and-test/prepare-your-o365-tenant.md) +## Prerequisites -> [!TIP] -> [GitHub Codespaces](https://github.com/features/codespaces) offers free plan up to a fixed amount of usage per month. If you need to free up more space, go to [github.com/codespaces](https://github.com/codespaces) and delete the codespaces that you no longer need. +Ensure you install the following tools for building and deploying your apps. + + |   | Install | For using... | + | --- | --- | --- | + | **Required** |   |   | + |   | [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript or TypeScript build environments. Use the latest version. | + |   | [Microsoft 365 Agents Toolkit](#install-microsoft-365-agents-toolkit) | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.| + |   | [Node.js](https://nodejs.org/en/download/) | Backend JavaScript runtime environment. For more information, see [Node.js version compatibility table](~/toolkit/build-environments.md#nodejs-version-compatibility-table-for-project-type).| + |   | [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Collaborate with people you work with through apps for chats, meetings, and calls in one place.| + |   | [Microsoft Edge](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools essential for debugging and testing. | + |   | [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with appropriate permissions to install a custom app. | + | **Optional** |   |   | + |   | [Azure Tools for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) and [Azure CLI](/cli/azure/install-azure-cli) | Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure. | + |   | [React Developer Tools for Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) or [React Developer Tools for Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/react-developer-tools/gpphkfbcpidddadnkolkpfckpihlkkil) | A browser DevTools extension for the open-source React JavaScript library. | + +[!INCLUDE [Set up prerequisites](../includes/get-started/prepare-toolkit.md)] + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+development+environment&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D1&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +### Get a free Azure account + +If you want to host your app or access resources in Azure, you must have an Azure subscription. [Create a free account](https://azure.microsoft.com/free/) before you begin. + +## Create project workspace for your message extension app + +Now, let's create your first message extension app. + +The message extension capability lets you interact with a web service through buttons and forms. Use the message compose area, command box, or a message directly in Teams client to search and initiate actions in an external system. Message extensions rely on bots to provide a dialog between the user and your code. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/your-helloworld-app-msgext.png" alt-text="Diagram shows Screenshot shows the different types of app features with message extension highlighted."::: + +There are two types of Teams message extensions: + +- [Search commands](../messaging-extensions/how-to/search-commands/define-search-command.md): You can search external systems and insert the results into a message in the form of a card. +- [Action commands](../messaging-extensions/how-to/action-commands/define-action-command.md): You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send the information back to Teams. + +Let's create a message extension app with a search command. First, set up a new Teams project for creating the message extension app. + +## Create your message extension project workspace + +If the prerequisites are in place, let's begin! + +> [!NOTE] +> The Visual Studio Code UI shown may differ for you depending on your operating system, Toolkit version, theme, and environment. + +# [Visual Studio Code](#tab/vsc1) + +1. Open Visual Studio Code. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the Visual Studio Code activity bar. -To create a search-based message extension app with GitHub Codespaces, follow these steps: +1. Select **Create a New Agent/App** > **Teams App**. -1. Select the following button to open GitHub Codespaces. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-project.png" alt-text="Screenshot shows the option to create a new app from the Agents Toolkit sidebar."::: - Open message extension in GitHub Codespaces +4. Select **Message Extension**. - You might be asked to sign in to GitHub account if you haven't already. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-new-app1.png" alt-text="Screenshot shows the option to create a new Teams app."::: -1. Select **Create new codespace**. +5. Select **Custom Search Results**. - :::image type="content" source="../assets/images/get-started/codespace.png" alt-text="Screenshot shows you the GitHub page to create a codespace for message extension."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: - The **Setting up your codespace** page appears. +6. Select **Start with a Bot**. - :::image type="content" source="../assets/images/get-started/building-codespace.png" alt-text="Screenshot shows you the codespace building your message extension."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-architecture-mex.png" alt-text="Screenshot shows the options for the architecture of the message extension."::: - Agents Toolkit prepares the message extension for you and opens it in VS Code in the browser. The Microsoft 365 Agents Toolkit icon appears in the activity bar of VS Code. +7. Select **JavaScript**. -1. Select **Sign in to your Microsoft 365** and **Sign in to Azure** to sign in with your Microsoft 365 account. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-language-tab.png" alt-text="Screenshot shows the option to select the programming language."::: - :::image type="content" source="../assets/images/get-started/codespace/me-sign-in.png" alt-text="Screenshot shows you the Agents Toolkit window in browser to sign in."lightbox="../assets/images/get-started/add-tab-in-teams.png"::: +8. Select **Default folder** to store your project root folder in default location. - > [!NOTE] - > - > When you build your app, GitHub Codespaces loads it to the Teams client in a new tab. If your browser blocks pop-up tabs or windows, you'll need to allow pop-ups for your app to open. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-default-location.png" alt-text="Screenshot shows the selection of default location."::: -1. Select **Preview your Teams App (F5)** to build your message extension. +You can also change the default location by the following steps: - :::image type="content" source="../assets/images/get-started/codespace/me-preview-teams.png" alt-text="Screenshot shows you the Agents Toolkit window in browser with your message extension."lightbox="../assets/images/get-started/codespace/me-preview-teams.png"::: +1. Select **Browse**. - GitHub Codespaces builds your message extension app, loads it to Teams client, and opens in a separate browser tab. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-browse.png" alt-text="Screenshot shows the browse option."::: -1. Select **Add** to install your message extension in Teams. +2. Select the location for project workspace. - :::image type="content" source="../assets/images/get-started/codespace/me-in-teams.png" alt-text="Screenshot of the app details dialog to add the message extension app in Teams."::: +3. Select **Select Folder**. -1. Select **Open** to open the app in personal scope. + :::image type="content" source="../assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: - :::image type="content" source="../assets/images/get-started/codespace/me-in-teams-scope.png" alt-text="Screenshot of the scope selection dialog to open the app in personal scope."::: +4. Enter a suitable name for your app. Select **Enter**. - You've successfully created the search-based message extension and loaded in the Teams client. + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: - :::image type="content" source="../assets/images/get-started/codespace/me-teams-chat.png" alt-text="Screenshot shows your message extension loaded in the Teams client."::: +Agents Toolkit creates the app in a few seconds. - > [!div class="nextstepaction"] - > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Build+a+message+extension+app+using+GitHub+Codespaces&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fget-started%2Fbuild-message-extension%3Ftabs%3Dagentstoolkitcodespaces&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fget-started%2Fbuild-message-extension.md&documentVersionIndependentId=4f4e5027-7a0b-30e1-dc4b-d2bd8daee892&platformId=03898b42-3609-cc37-16a8-a24f488a9b12&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-created-mex.png" alt-text="Screenshot shows the newly created message extension app." lightbox="../assets/images/toolkit-v2/first-msgext/app-created-mex.png"::: -# [Step-by-step guide](#tab/step-by-step-guide) +After your app is created, Agents Toolkit displays the following message: -If you want to learn how to start a project with Agents Toolkit from the beginning, you'll need to set up your development environment. Select the following button to start building your message extension app. +:::image type="content" source="../assets/images/toolkit-v2/preview-project-msg.png" alt-text="Screenshot shows a dialog saying that the message extension app is created."::: > [!div class="nextstepaction"] -> [Build your first message extension app using JavaScript](../sbs-gs-msgext.yml) +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Create+your+message+extension+project+workspace+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D2&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) ---- +# [Command Line](#tab/cli1) + +Use the `atk' CLI to create your first project. + +1. Go to the folder where you want to create the project folder and open Command Prompt. + +1. Enter the following command to create a new Teams app: + +``` bash +atk new +``` + +3. CLI provides you with a series of options to choose from. Use arrow keys to select an option. After you make the choice, select Enter to confirm. + +4. Select **Message Extension** for **New Project**. +5. Select **Custom Search Results** for **App Features Using a Message Extension**. +6. Select **Start with a Bot** for **Architecture of Search Based Message Extension**. +7. Select **JavaScript** for **Programming Language**. +8. Select **Enter** to select the default workspace folder for your app. +9. Enter a suitable name for your app. The name of the app must consist only of alphanumeric characters. + +CLI creates the project after you answer all the questions. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Create+your+message+extension+project+workspace+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Ccli1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D2&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- + +## Take a tour of the message extension app source code + +A message extension uses Bot Framework to interact with your service through a conversation. After scaffolding, view the project directories and files under **EXPLORER**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/folder-structure-mex-app.png" alt-text="Screenshot shows the files of the message extension app."::: + + | Folder / File | Contents | + | --- | --- | + | `m365agents.yml` | Main project file describes your application configuration and defines the set of actions to run in each lifecycle stage. | + | `m365agents.local.yml` | Overrides `m365agents.yml` with actions that enable local execution and debugging. | + | `.vscode/` | Visual Studio Code files for local debug. | + | `appPackage/` | Templates for the Teams application manifest. | + | `infra/` | Templates for provisioning Azure resources. | + | `index.js` | Application entry point and `express` handler. | + +> [!Tip] +> Familiarize yourself with bots and message extension outside of Teams before you integrate your app within Teams. + +## Build and run your first message extension app + +After you set up your project workspace with Agents Toolkit, it's time to build your project. You need to sign in to your Microsoft 365 account. + +### Sign in to your Microsoft 365 account + +Sign in with the admin account you created while joining the Microsoft 365 developer program. + +# [Visual Studio Code](#tab/vsc2) + +1. Open Visual Studio Code. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar. + +1. Select **Sign in to Microsoft 365** using your credentials. Your default web browser opens to let you sign in. + + :::image type="content" source="../assets/images/toolkit-v2/toolkit-sign-in-m365.png" alt-text="Screenshot shows where to sign in to Microsoft 365 and Azure."::: + +4. Close the browser after signing in using your credentials. + +5. Return to Agents Toolkit within Visual Studio Code. + +The **ACCOUNTS** section of the sidebar shows your Microsoft 365 account name. If custom app upload is enabled for your Microsoft 365 account, Agents Toolkit displays **Custom App Upload Enabled**. + + :::image type="content" source="../assets/images/toolkit-v2/first-tab/m365-uploading-enabled-msg.png" alt-text="Screenshot shows the user signed in to Microsoft 365 and the uploading enabled message."::: + +Now you're ready to build the app and run it locally! + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Microsoft+365+account+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Line](#tab/cli2) + +1. Go to the project folder of your message extension app and open Command Prompt. + +1. Sign in to Microsoft 365 with Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI) command: + +``` bash + atk account login m365 +``` + +Your default web browser opens to let you sign in. Sign in to your Azure account using your credentials. Close the browser when you're prompted. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Microsoft+365+account+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Ccli1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- + +## Build and run your app in the local environment + +Now you can build and debug your first Teams message extension app locally. + +### Build and run your app locally + +1. Select the **F5** key in Visual Studio Code to run your application in debug mode. + +> [!NOTE] +> If Agents Toolkit is unable to verify a particular prerequisite, it prompts you to check. + +
+
+Learn what happens when you run your app locally in the debugger. + +When you select **F5**, Agents Toolkit performs the following functions: + +1. Checks the following prerequisites: + + 1. You're signed in with a Microsoft 365 account. + 1. Custom app upload is enabled for your Microsoft 365 account. + 1. Supported Node.js version is installed. + 1. Port required by bot app is available. + +2. Installs npm packages +3. Starts Dev Tunnel to create an HTTP tunnel. +4. Registers the app in Microsoft Entra ID and configures the app. +5. Registers the bot app in Bot Framework and configures the app. +6. Registers the app in Teams Developer Portal and configures the app. +7. Starts the message extension app hosted locally. +8. Starts Teams in a web browser and uploads the Teams app. + +
+ +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/f5-build-and-run-mex.png" alt-text="Screenshot shows the debug process of the message extension app." lightbox="../assets/images/toolkit-v2/first-msgext/f5-build-and-run-mex.png"::: + +When you debug the app for the first time, Teams downloads the dependencies and builds the app. This process can take 3 to 5 minutes to complete. + +1. Teams opens in a browser window when the build is complete. Sign in with your Microsoft 365 account, if prompted. + +1. A dialog box opens to let you add the message extension app to Teams. Select **Add**. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: + + Teams loads the message extension app. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: -For more information on message extensions, see [message extensions](../messaging-extensions/what-are-messaging-extensions.md). +As message extension apps rely on bots for enabling communication between the user and the web service, your app loads in to a chat feature of a bot. -If a bot is what you are interested in, select the following: +- If you created a bot app before you created the message extension app, Teams loads the message extension in the bot app you created. Previous chat messages of the bot app are visible. +- If you created a message extension first, Teams loads your app in the most recent chat that is open on Teams. > [!div class="nextstepaction"] -> [Start building a bot](build-notification-bot.md) +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Build+and+run+your+app+locally&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -If you want to build basic tab app, select the following: +### Test your app + +The first time your app loads, the message extension app is open for you to test. This sample app lets you search open-source npm packages from the software registry. + +### How to run a search query + +# [Message Extension](#tab/msgext) + +1. Enter the name of an open-source npm package in the search box of the message extension, such as **cli**. The message extension displays a list of the matching items. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-string.png" alt-text="Screenshot shows a search string in the message extension app."::: + +2. Select one of the items from the list. The app creates an Adaptive Card with the item in the message compose area so you can send it in a chat or channel. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-result.png" alt-text="Screenshot shows the search result in the message compose area."::: + +3. Select **Enter**. The message extension app sends the Adaptive Card with the item in the chat or channel. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-sent.png" alt-text="Screenshot shows the search result sent in chat."::: + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Message+Extension&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Box](#tab/cmdbox) + +1. Enter **/** followed by your message extension app's name in the command box. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: + + The message extension app opens in the command box. + +2. Enter a name of an open-source npm package and select one of the search results. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-box-search.png" alt-text="Screenshot shows a search string in the command box."::: + +The message extension displays the search result as an Adaptive Card in the command box. +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card.png" alt-text="Screenshot shows the search result as a card in the command box."::: + +3. Copy the Adaptive Card to paste it in the message compose area. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-send.png" alt-text="Screenshot shows search result in a card in the message compose area."::: + +4. Select **Enter**. The message extension app sends the Adaptive Card with the search result in the most recent chat. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-sent.png" alt-text="Screenshot shows the search result sent in a chat."::: + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Command+Box&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Ccmdbox%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- + +### How to open your message extension app + +You tested the search feature of the message extension app in the previous step. Now, learn the different ways to open the message extension app. +
+
+
+ Open your app from command box + +1. Enter **/** followed by your message extension app's name in the command box. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app in the command box."::: + +The app opens in the command box and you can use it to run a query. + +> [!NOTE] +> +> - Using **/** to open your message extension app from the command box only works in the new Teams client. +> - Use **@** to open your message extension app from the command box in the classic Teams client. + +
+ +
+
+ Open your app from message compose area + +1. Select the three dots at the bottom of the message compose area. + +2. Select your message extension app. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/three-dot-mex.png" alt-text="Screenshot shows how to open the message extension app from message compose area."::: + +The message extension app loads with the options to run a search. + +
+ +
+
+Open your app from uploaded custom apps + +1. Select **Apps** > **Manage your apps**. + +1. Select the dropdown for your app from the list of apps and select **Personal app**. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/uploaded-apps.png" alt-text="Screenshot shows the uploaded apps in Teams."::: + +3. A dialog box appears suggesting you to try out your app. If you select **Got it**, the dialog box disappears. Select **Try it**. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-try-it.png" alt-text="Screenshot shows the message to try the message extension app now or later."::: + +4. A list of your message extension apps appears in your most recent Teams chat. Select your message extension app from the list. + +
+ +### Learn how to troubleshoot if your app doesn't run locally + +To run your app in Teams, you must have a Microsoft 365 development account that allows custom app upload. You can learn more about custom app upload in the Prerequisites section. + +## Deploy your first Teams app + +Let's deploy your first message extension app on Azure using Agents Toolkit. + +### Sign in to your Azure account + +Sign in to your Azure account to access the Microsoft Azure portal and provision new cloud resources to support your app. + +# [Visual Studio Code](#tab/vsc3) + +1. Open Visual Studio Code. + +1. Open the project folder in which you created the message extension app. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar. + +1. Select **Sign in to Azure** using your credentials. Your default web browser opens to let you sign in. + +> [!TIP] +> If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step. + +5. Close the browser when prompted and return to Visual Studio Code. + +The **ACCOUNTS** section of the sidebar lists the number of usable Azure subscriptions available to you. Ensure that you have at least one usable Azure subscription available. If not, sign out and use a different account. > [!div class="nextstepaction"] -> [Build your basic tab app](build-basic-tab-app.md) +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Azure+account+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Line](#tab/cli3) + +1. Go to the project folder of your message extension app and open Command Prompt. + +1. Sign in to Azure with Agents Toolkit CLI command: -## Next step +``` bash +atk account login azure +``` + +3. Your default web browser opens to let you sign in. Sign in to your Azure account using your credentials. Close the browser when you're prompted. + +Now, let's learn how to deploy the app to Azure using Agents Toolkit. > [!div class="nextstepaction"] -> [Tool options and code samples](tool-options-and-code-samples.md) +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Azure+account+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Ccli2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +--- + +[!INCLUDE [Provision and Deploy your app on Azure](../includes/get-started/azure-provisioning-instructions.md)] + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Deploy+your+app+to+Azure&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Ccli2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +### Learn what happens when you deployed your app to Azure + +Before deployment, the app runs locally. + +- The backend runs using Azure Functions Core Tools. +- The application HTTP endpoint, where Microsoft Teams loads the application, runs locally. + +Deployment is a two-step process. You provision the resources on an active Azure subscription and then deploy or upload the backend and frontend code of the app to Azure. + +- The backend, if configured, uses various Azure services including Azure App Service and Azure Storage. +- The frontend app is deployed to an Azure Storage account configured for static web hosting. + +### Congratulations + +You completed the tutorial to build a message extension app with JavaScript! -## See also +Did you come up with something like this? -[npm directory](https://www.npmjs.com/) + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png" alt-text="Screenshot shows the final output of the message extension app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png":::