Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2907 from MicrosoftDocs/hello-world
Edit hello world section and add more images
- Loading branch information
Showing
33 changed files
with
574 additions
and
528 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified
BIN
+16.6 KB
(160%)
msteams-platform/assets/images/build-your-first-app/VSC-install-toolkit.PNG
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+92.7 KB
...s-platform/assets/images/build-your-first-app/personal-tab-tutorial-content.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+63.2 KB
...form/assets/images/build-your-first-app/personal-tab-tutorial-updated-theme.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+159 KB
msteams-platform/assets/images/build-your-first-app/teams-client-bot.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+93.7 KB
msteams-platform/assets/images/build-your-first-app/teams-client-helloworld.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+348 KB
msteams-platform/assets/images/build-your-first-app/vscode-teams-toolkit-01.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+58.7 KB
msteams-platform/assets/images/build-your-first-app/vscode-teams-toolkit-02.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+111 KB
msteams-platform/assets/images/build-your-first-app/vscode-teams-toolkit-03.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+68.5 KB
msteams-platform/assets/images/build-your-first-app/vscode-teams-toolkit-04.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+183 KB
msteams-platform/assets/images/build-your-first-app/vscode-teams-toolkit-05.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+179 KB
...-platform/assets/images/build-your-first-app/vscode-teams-toolkit-appstudio.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+58.7 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-01.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+116 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-02.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+103 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-03.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+122 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-04.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+236 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-05.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+244 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-07.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+214 KB
...tform/assets/images/build-your-first-app/vscode-teams-toolkit-bots-ngrok-06.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+248 KB
...platform/assets/images/build-your-first-app/vscode-teams-toolkit-install-08.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+202 KB
...ms-platform/assets/images/build-your-first-app/vscode-teams-toolkit-install.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified
BIN
+5.87 KB
(120%)
msteams-platform/assets/images/tabs/channel-tab-tutorial-content-installed.PNG
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified
BIN
+3.81 KB
(130%)
msteams-platform/assets/images/tabs/channel-tab-tutorial-content.PNG
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
203 changes: 157 additions & 46 deletions
203
msteams-platform/build-your-first-app/build-and-run.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,81 +1,192 @@ | ||
--- | ||
title: Get started - Build and run your first app | ||
author: heath-hamilton | ||
author: girliemac | ||
description: Quickly create a Microsoft Teams app that displays a "Hello, World!" message using the Microsoft Teams Toolkit. | ||
ms.author: lajanuar | ||
localization_priority: Normal | ||
ms.date: 11/03/2020 | ||
ms.author: timura | ||
ms.date: 03/22/2021 | ||
ms.topic: quickstart | ||
--- | ||
# Build and run your first Microsoft Teams app | ||
# Create your first Microsoft Teams app | ||
|
||
Start Microsoft Teams development by building a personal tab that displays "Hello, World!". | ||
Build and run your first Teams app using the following steps: | ||
This quickstart teaches you to build and run Microsoft Teams app that displays "Hello, World!" | ||
|
||
## Prerequisites | ||
|
||
Before you begin, you need to [set up your Teams development tenant](#set-up-your-teams-development-tenant) and [install your Teams development tools](#install-your-development-tools). | ||
|
||
### Set up your Teams development tenant | ||
|
||
A **tenant** is like a container for an organization. In Teams terms, a tenant is where people from that org chat, share files, and run meetings. As a developer, you need a tenant to sideload and test the Teams apps that you are building. | ||
|
||
# [Do not have a tenant](#tab/do-not-have-a-tenant) | ||
|
||
You can get a free Teams test account, which includes a tenant that allows app sideloading, by joining the Microsoft 365 developer program. The registration process takes approximately two minutes. | ||
|
||
**To get a tenant** | ||
|
||
1. Go to the [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program). | ||
1. Select **Join Now** and follow the onscreen instructions. | ||
1. In the Welcome screen, select **Set up E5 subscription**. | ||
1. Set up your Microsoft 365 developer account. | ||
After you finish, the following screen appears: | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/dev-program-subscription.png" alt-text="Example of what you see after signing up for the Microsoft 365 developer program."::: | ||
|
||
1. Sign in to Teams with your new account. | ||
1. In the Teams client, select **Apps**. | ||
1. Verify that you can see the **Upload a custom app** option. If you do, this means you can sideload apps. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/upload-custom-app-closeup.png" alt-text="Illustration showing where in Teams you can upload a custom app."::: | ||
|
||
# [Have a tenant](#tab/have-a-tenant) | ||
|
||
If you already have a tenant, verify if you can sideload apps in Teams. | ||
|
||
**Verify that you can sideload your apps** | ||
|
||
1. In the Teams Client, select **Apps**. | ||
1. Verify that you can see the **Upload a custom app** option. If you do, this means you can sideload apps. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/upload-custom-app-closeup.png" alt-text="Illustration showing where in Teams you can upload a custom app."::: | ||
|
||
--- | ||
|
||
### Install your development tools | ||
|
||
To build this app, you'll use the Teams Toolkit for Visual Studio Code to quickly get started. You can also build Teams apps with any ofyour preffered tools. | ||
|
||
> [!NOTE] | ||
> Teams displays app content only through HTTPS connections. To debug certain types of apps locally, such as a bot, you'll learn how to use ngrok to set up a secure tunnel between Teams and your app. | ||
> | ||
> Production Teams apps are hosted in the cloud. | ||
**To install Microsoft Teams tools** | ||
|
||
1. Install [Node.js](https://nodejs.org/en/). | ||
1. If you plan to build a bot or messaging extension, install [ngrok](https://ngrok.com/download) and [expose your localhost to the Internet using ngrok](../tutorials/get-started-dotnet-app-studio.md#tunnel-using-ngrok). | ||
1. Install the latest version of [Visual Studio Code](https://code.visualstudio.com/download). | ||
|
||
> [!NOTE] | ||
> The toolkit does not support earlier versions of Visual Studio Code. | ||
1. In the left activity bar, select **Extensions** :::image type="icon" source="../assets/icons/vs-code-extensions.png":::. | ||
1. In **Microsoft Teams Toolkit**, select **Install**. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/vsc-install-toolkit.png" alt-text="Illustration showing where in Visual Studio Code you can install the Microsoft Teams Toolkit extension."::: | ||
|
||
## 1. Create your app project | ||
|
||
Use the Microsoft Teams Toolkit in Visual Studio Code to set up your first app project. Create your app project using the following steps: | ||
1. Open Visual Studio Code. | ||
1. Select **Microsoft Teams Toolkit** :::image type="icon" source="../assets/icons/vsc-toolkit.png"::: > **Create a new Teams app**. | ||
|
||
1. In Visual Studio Code, select **Microsoft Teams** :::image type="icon" source="../assets/icons/vsc-toolkit.png"::: on the left Activity Bar and choose **Create a new Teams app**. | ||
1. When prompted, sign in with your Microsoft 365 development account. | ||
1. On the **Add capabilities** screen, select **Tab** then **Next**. | ||
:::image type="content" source="../assets/images/build-your-first-app/choose-tab.png" alt-text="Screenshot showing how to configure your app project with the Visual Studio Code Teams Toolkit."::: | ||
1. Enter a name for your Teams app. (This is the default name for your app and also the name of the app project directory on your local machine.) | ||
1. Check only the **Personal tab** option and select **Finish** at the bottom of the screen to configure your project. | ||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-02.png" alt-text="Screenshot showing how to create your app project with the Visual Studio Code Teams Toolkit."::: | ||
|
||
1. Sign in with your Microsoft 365 development account. Either the one you just created or the account you already had that allows app sideloading. | ||
1. On the **Select project** screen, go to **Personal app** and select **JS** (JavaScript) > **Next**. | ||
|
||
## 2. Understand important app project components | ||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-03.png" alt-text="Screenshot showing how to configure your app project with the Visual Studio Code Teams Toolkit."::: | ||
|
||
Once the toolkit configures your project, you have the components to build a basic personal tab for Teams. The project directories and files display in the Explorer area of Visual Studio Code. | ||
1. Enter a name for your Teams app. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/app-project-files.png" alt-text="Screenshot showing app project files for a personal tab in Visual Studio Code."::: | ||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-04.png" alt-text="Screenshot showing how to add a name to your app project with the Visual Studio Code Teams Toolkit."::: | ||
|
||
### App scaffolding | ||
1. Select **Finish**. | ||
Your project is now configured. | ||
|
||
The toolkit automatically creates scaffolding for you in the `src` directory based on the capabilities you added during setup. | ||
## 2. Understand your app project components | ||
|
||
If you create a tab during setup, for example, the `App.js` file in the `src/components` directory is important because it handles the initialization and routing of your app. It calls the [Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md) to establish communication between your app and Teams. | ||
After the toolkit configures your app project, you have the components to build your "Hello, World!" Teams app. The project's directories and files are located in the Visual Studio Code Explorer. | ||
|
||
### App ID | ||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-05.png" alt-text="Screenshot showing the scaffolding in your app project with the Visual Studio Code Teams Toolkit."::: | ||
|
||
Configure your app with App Studio using the Teams app ID. Find the ID in the `teamsAppId` object, which is located in your project's `package.json` file. | ||
The toolkit automatically creates app scaffolding in the `src` directory based on the capabilities you added during setup. | ||
Since you created a tab during setup, the `App.js` file in the `src/components` directory handles the initialization and routing of your app. The file also calls the Microsoft Teams JavaScript client SDK to establish communication between your app and Teams. | ||
|
||
## 3. Build and run your app | ||
|
||
Build and run your app locally to save time. This information is also available in the toolkit `README`. Build and run your app using the following steps: | ||
Build and run your app locally to save time. | ||
|
||
1. In a terminal, go to the root directory of your app project and run `npm install`. | ||
1. Run `npm start`. | ||
**To build and run your app** | ||
|
||
Once complete, there's a **Compiled successfully!** message in the terminal. Your app is running on `https://localhost:3000`. | ||
1. In Visual Studio Code, select **View** > **Terminal**. | ||
1. Run `npm install`. | ||
1. Run `npm start`. | ||
|
||
A **Compiled successfully!** message appears in the terminal. Your app is now running on your localhost at `https://localhost:3000`. | ||
|
||
## 4. Sideload your app in Teams | ||
|
||
Your app is ready to test in Teams. To do this, you must have a Microsoft 365 development account that allows app sideloading. For more information on account opening, see [Teams development account](../build-your-first-app/build-first-app-overview.md#set-up-your-development-account). | ||
Sideloading is the process of installing an app in Teams that hasn't been approved by your admin or Microsoft. Sideloading is common when testing and debugging Teams apps. | ||
|
||
> [!TIP] | ||
> Check for issues before sideloading your app, using the [validation feature in App Studio](../concepts/deploy-and-publish/appsource/prepare/submission-checklist.md#teams-app-validation-tool), which is included in the toolkit. Fix the errors to successfully sideload the app. | ||
By default, Teams doesn't allow app sideloading. You can change this setting in the Teams admin center. | ||
|
||
Sideload your app in Teams using the following steps: | ||
**To enable app sideloading in Teams** | ||
|
||
> [!NOTE] | ||
> To enable sideloading before you sideload your app in Teams, follow the steps in [Turn on app sideloading](../concepts/build-and-test/prepare-your-o365-tenant.md#enable-custom-teams-apps-and-turn-on-custom-app-uploading). | ||
1. Sign in to the [Microsoft 365 admin center](https://admin.microsoft.com/Adminportal/Home?source=applauncher#/homepage#/) with your admin credentials. | ||
1. Select **Show All** > **Teams**. | ||
|
||
1. Select the **F5** key to launch a Teams web client in Visual Studio Code. | ||
1. To display your app content in Teams, specify that where your app is running (`localhost`) is trustworthy: | ||
1. Open a new tab in the same browser window (Google Chrome by default) which opened after pressing **F5**. | ||
1. Go to `https://localhost:3000/tab` and proceed to the page. | ||
1. Go back to Teams. In the dialog, select **Add for me** to install your app. | ||
:::image type="content" source="../assets/images/build-your-first-app/tab-running.png" alt-text="Screenshot showing an example 'Hello, World!' personal tab app running in Teams."::: | ||
![image of admin center menu](~/assets/images/prepare-test-tenant/admin-center.png) | ||
|
||
🎉 Congratulations! Your app is running in Teams. | ||
> [!Note] | ||
> It can take up to 24 hours for the **Teams** option to appear. | ||
## Next step | ||
1. Go to **Teams apps** > **Setup policies** > **Global** (Org-wide default). | ||
|
||
Expand on the personal tab you just created or build another type of Teams app. | ||
![turn on sideload view](~/assets/images/prepare-test-tenant/turn-on-sideload.png) | ||
|
||
1. Turn on the **upload custom apps** toggle. | ||
|
||
1. Select **Save** to save the changes. | ||
|
||
Your test tenant now allows custom app sideloading. | ||
|
||
> [!Note] | ||
> Check for issues before sideloading your app using the validation feature in App Studio, which is included in the toolkit. Fix the errors to successfully sideload the app. | ||
|
||
### Sideload your app | ||
|
||
1. In Visual Studio Code, open the Teams Toolkit. | ||
1. Go to **App Studio**. | ||
1. Select **Test and Distribute** > **Install**. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-appstudio.png" alt-text="Screenshot showing how to sideload your app to Teams client with the Visual Studio Code Teams Toolkit."::: | ||
|
||
**Alternatively** | ||
|
||
1. Select the **F5** key to open browser window to install. This will skip the installation process in the **App Studio** and lauch Teams in your browser. | ||
1. In the installation dialog, select **Add** to install your app to Teams. | ||
|
||
:::image type="content" source="../assets/images/build-your-first-app/vscode-teams-toolkit-install.png" alt-text="Screenshot showing how to sideload your app to Teams client."::: | ||
|
||
> [!Note] | ||
> App Studio is also available as a stand-alone app for Teams client. | ||
### Troubleshoot sideloading issues | ||
|
||
**Installation failed** | ||
|
||
If the `Manifest parsing has failed` error message appears while installing your app, verify that the app information is correctly entered. | ||
|
||
**To verify the app information** | ||
|
||
* In the Teams Toolkit, go to **App Studio** > **App details** and verify that all the required information is correctly entered. | ||
* If you manually edited the `manifest.json` file, verify that the JSON is well-defined in the **App Manifest** tool in App Studio. | ||
|
||
**Tab content not displayed** | ||
|
||
Verify that your app is running. If it isn't, go to the terminal and run `npm start`. | ||
|
||
## See also | ||
|
||
* [Prepare your Microsoft 365 tenant](https://docs.microsoft.com/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | ||
* [Choosing a setup to test and debug your Microsoft Teams app](../concepts/build-and-test/debug.md) | ||
* [Building tabs and other hosted experiences with the Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md) | ||
* [Prepare for AppSource submission](../concepts/deploy-and-publish/appsource/prepare/submission-checklist.md) | ||
* [Quickly develop apps with App Studio for Microsoft Teams](../concepts/build-and-test/app-studio-overview.md) | ||
* [Build a channel tab](../build-your-first-app/build-channel-tab.md) | ||
|
||
## Next step | ||
|
||
> [!div class="nextstepaction"] | ||
> [Add to your personal tab](../build-your-first-app/build-personal-tab.md) | ||
> [!div class="nextstepaction"] | ||
> [Build a channel tab](../build-your-first-app/build-channel-tab.md) | ||
> [!div class="nextstepaction"] | ||
> [Build a bot](../build-your-first-app/build-bot.md) | ||
> [Build a personal tab for Microsoft Teams](../build-your-first-app/build-personal-tab.md) |
Oops, something went wrong.