-
Notifications
You must be signed in to change notification settings - Fork 204
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 #8710 from OfficeDev/chyuan/update-upgrade-report
docs: update upgrade report
- Loading branch information
Showing
1 changed file
with
27 additions
and
29 deletions.
There are no files selected for viewing
56 changes: 27 additions & 29 deletions
56
packages/fx-core/templates/core/v3Migration/upgradeReport.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,50 +1,48 @@ | ||
| # Upgrade Summary | ||
| # Review project upgrade and changes | ||
|
|
||
| Congratulations! You can continue your development now. Your project has been upgraded to work with the latest Teams Toolkit. | ||
| Your project was automatically upgraded to work with this version of Teams Toolkit. The upgrade is one-way, and you will not be able to use the version of Teams Toolkit in which it was originally created unless you [roll back the changes](#how-to-roll-back-after-the-upgrade). | ||
|
|
||
| Most of existing features behave similar with previous Teams Toolkit. You can visit https://aka.ms/teamsfx-v5.0-guide to learn the new features. And read [Important changes to your development flow](#important-changes-to-your-development-flow) to understand the changes to your development flow. | ||
|
|
||
| Visit https://aka.ms/teams-toolkit-5.0-upgrade to learn more about the upgrade. | ||
| > If you encountered a problem after the automatic upgrade, review the [known issues](https://aka.ms/teams-toolkit-5.0-upgrade#known-issues). If you are still having trouble, contact [email protected] or [file an issue on GitHub](https://github.com/officedev/teamsfx/issues) with details about the problem. | ||
| ## Important changes to your development flow | ||
|
|
||
| There's no immediate action required from you. This part illustrates what's changed to your development flow. | ||
| > If you encountered any errors or issues after upgrade, you could try the following steps or visit [known issues](https://aka.ms/teams-toolkit-5.0-upgrade#known-issues) for details. | ||
| The new features in this release make developing your apps simpler and more flexible, but also include changes to how the toolkit creates projects, automates configuration, and deploys resources. Visit [the upgrade guide](https://aka.ms/teamsfx-v5.0-guide) for more info about all of the changes. | ||
|
|
||
| Some of the changes you may immediately notice are: | ||
|
|
||
| * Configuration of the lifecycle management using Provision, Deploy, and Publish are now fully customizable and expressed in `teamsapp.local.yml` and `teamsapp.yml`. [More info](https://aka.ms/teamsfx-v5.0-guide#project-files) | ||
| * Configuration and values that were saved in `.fx/config` and `.fx/state` are now handled with environment files and saved to `/env` by default. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) | ||
| * The changes to use environment files give greater flexibility of configuring which resources are used to provision, but may require some manual steps when creating new environments. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) | ||
|
|
||
| 1. You need to sync `env/.env.{env}.user` files between different machines manually. All these files will be gitignored by default. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) | ||
| 2. You need to take some manual steps when creating or provisioning new environments for your old project. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) | ||
| 3. You need to manually update `.vscode/launch.json` when launching your app for a certain environment if your current project contains it. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#launch-your-app) | ||
| 4. You need to provide values to `APIM__PUBLISHEREMAIL` and `APIM__PUBLISHERNAME` environment variable if your current project uses APIM. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#provision-apim-service) | ||
| 5. You need to manually update `Start local tunnel` task in `.vscode/task.json` if you have customized this task. Teams Toolkit now uses Dev Tunnel as default tunnel solution. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#start-tunnel-service) | ||
| If you're using APIM: | ||
| * You need to provide values to `APIM__PUBLISHEREMAIL` and the `APIM__PUBLISHERNAME` environment variables. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#provision-apim-service) | ||
|
|
||
| You can visit this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#feature-changes-that-impact-your-development-flow) to learn more changes to Teams Toolkit. | ||
| You can [view these changes on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#feature-changes-that-impact-your-development-flow). | ||
|
|
||
| ## Changes to your project | ||
| ## Changes to your project file structure | ||
|
|
||
| 1. Created `teamsapp.yml` and `teamsapp.local.yml` in your project root folder. | ||
| 1. Created `teamsapp.yml` and `teamsapp.local.yml` in your project's root directory. | ||
| 2. Moved environment files in `.fx` to `.env.{env}` in `env` folder. | ||
| 3. If your project contains file `.fx/states/{env}.userdata`, the content will be moved to `.env.{env}.user` in `env` folder | ||
| 4. Moved `templates/appPackage` to `appPackage`, renamed `manifest.template.json` to `manifest.json` and placeholders in it will be updated per the latest Teams Toolkit requirement. | ||
| 5. If your project contains file `templates/appPackage/aad.template.json`, it will be moved and renamed as `aad.manifest.json` and placeholders in it will be updated per the latest Teams Toolkit requirement. | ||
| 4. Moved `templates/appPackage` to `appPackage`, renamed `manifest.template.json` to `manifest.json` and placeholders in it will be updated using the latest default conventions. | ||
| 5. If your project contains `templates/appPackage/aad.template.json`, it will be moved and renamed to `aad.manifest.json` and the templated variables names are updated to the latest default conventions. | ||
| 6. If your project contains file `.vscode/tasks.json` and `.vscode/launch.json`, they will be updated. | ||
| 7. Updated `.gitignore` to ignore new environment user files. | ||
| 8. Removed `.fx` folder. | ||
|
|
||
| For more detailed changes, please refer to this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#file-changes). | ||
| You can [view these changes on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#file-changes). | ||
|
|
||
| ## Known issues | ||
|
|
||
| 1. If your project only contains a bot, you may meet error that complains `STATE__FX_RESOURCE_FRONTEND_HOSTING__ENDPOINT` is missing when executing commands. Replace this placeholder with a valid URL in `appPackage/manifest.json` to fix it. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#state__fx_resource_frontend_hosting__endpoint-missing-error-in-some-projects) | ||
|
|
||
| 2. If your project is created with Visual Studio version < 17.4, you may see error `InvalidParameter: Following parameter is missing or invalid for aadApp/create action: name` when executing commands. Please follow [the steps](#how-to-roll-back) to roll back, install VS 17.4 and run upgrade first. | ||
|
|
||
| 3. If your tab app is created with Teams Toolkit 3.2.0 or earlier version, you may see error `simpleAuthEndpoint in configuration is invalid` when remote debugging your app. Please follow this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#simpleauthendpoint-in-configuration-is-invalid) to learn how to mitigate this error. | ||
| 4. If your project can be provisioned successfully before, but after upgrade it cannot be provisioned or published by `teamsApp/validateAppPackage` actione, please use the [validation](https://dev.teams.microsoft.com/validation) to check your appPackage zip file and fix the error. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#teamsappvalidateapppackage-failed-error) | ||
| 1. If your project only contains a bot, you might get an error about `STATE__FX_RESOURCE_FRONTEND_HOSTING__ENDPOINT` missing when running Provision or using Start Debugging. Find this placeholder variable in `appPackage/manifest.json` and replace it with a valid URL to resolve this issue. [More Info](https://aka.ms/teams-toolkit-5.0-upgrade#state__fx_resource_frontend_hosting__endpoint-missing-error-in-some-projects) | ||
| 2. If your project is created with Visual Studio version < 17.4, you might get an error like `InvalidParameter: Following parameter is missing or invalid for aadApp/create action: name` when running commands. [Try these steps](#how-to-roll-back-after-the-upgrade) to roll back the changes, install VS 17.4, and run the upgrade again. | ||
| 3. If your tab app is created with Teams Toolkit 3.2.0 or an earlier version, you may get an error like `simpleAuthEndpoint in configuration is invalid` when remote debugging your app. [Try these steps](https://aka.ms/teams-toolkit-5.0-upgrade#simpleauthendpoint-in-configuration-is-invalid) to learn how to mitigate this error. | ||
| 4. If your project was successfully provisioned before, but after upgrading it cannot be provisioned or published using the `teamsApp/validateAppPackage` action, try using the [validation report in Teams Developer Portal](https://dev.teams.microsoft.com/validation) to check the manifest for errors. [More Info](https://aka.ms/teams-toolkit-5.0-upgrade#teamsappvalidateapppackage-failed-error) | ||
|
|
||
| ## How to roll back | ||
| ## How to roll back after the upgrade | ||
|
|
||
| If you want to restore your project configuration after the upgrade is successful and continue to use old version Teams Toolkit, you can follow these steps: | ||
| 1. Copy everything in `.backup` folder to your project root folder | ||
| 2. Delete the new files mentioned in [Changes to your project](#changes-to-your-project) section | ||
| Follow these steps if you want to restore your project configuration after the upgrade is successful or need to use a previous version of Teams Toolkit: | ||
| 1. Copy everything in the `.backup` folder that was generated during the upgrade to your project root folder. | ||
| 2. Delete the new files created during the upgrade. The [Changes to your project](#changes-to-your-project) section contains info on everything that was created. | ||
|
|
||
| You can learn more details in this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#how-to-roll-back). | ||
| You can [view these steps on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#how-to-roll-back). |