Integrating Teams Toolkit with an existing bot project - OfficeDev/TeamsFx GitHub Wiki
Teams Toolkit can integrate with your existing Teams app project or infrastructure to enable a better development experience.
Prerequisites
- Teams Toolkit for VSCode v5
- (or) Teams Toolkit CLI v2
Make sure you have git enabled or some form of back up with your existing project in case errors happen.
Set up
- Create a new app with Teams Toolkit with bot capability.
- Your new project has the following project structure.
- We mainly need to work with
teamsapp.yml
andteamsapp.local.yml
. Learn more about Teams Toolkit yml files
Integrating the debugging process
Update Teams app manifest
-
Move your existing Teams manifest, color icon, and outline icon files into the new project, replacing the default ones. Teams Toolkit scaffolded projects save these files in the
appPackage
folder. If you choose to move these files to a different location, make sure you update actions inteamsapp.local.yml
that reference them. -
Update your manifest file. You can use
${{MY_VARIABLE_NAME}}
as placeholders inmanifest.json
, Teams Toolkit will replace them with their corresponding value at runtime. For a bot project, you usually need to use placeholders forid
,name.short
, andbots[].botId
. Make sure you save the values into an environment file.
Update environment variables
-
Teams Toolkit scaffolded projects come with 2 predefined environments, local and dev. We will use
local
for the debug process. More about environments -
Update
env/.env.local
with your existing Teams app and bot configurations.
- Update
env/.env.local.user
with your bot password.
- Here are some useful links to help you find your existing Teams app and bot configurations:
Integrate source code
- Move the source code from your existing project into the new Teams Toolkit project. This includes all the code for your bot to run, any adaptive cards and other necessary config files.
- Update your source code to reference environment variables, such as bot credentials, configurations, etc. Your can reference environment variables using
process.env
- Update
package.json
with the dependencies used by your existing project.
Replace Bot Framework with Azure Bot Service in the debugging process
- Teams Toolkit scaffolded projects use Bot Framework in the debugging process, however many existing projects and samples use Azure Bot Service. We need to update the new Teams Toolkit project to use Azure Bot Service for debugging.
- Update the provision stage in
teamsapp.local.yml
. Replace thebotFramework/create
action with thearm/deploy
action arm/deploy
reference Azure bicep files. By default, your Teams Toolkit scaffolded bot project generates these bicep files in theinfra/
folder. You may need to modify the default bicep files to fit your project. Note, the default bicep files are referenced byteamsapp.yml
for provisioning Azure resources. You can use environment variables to separate configurations, or create new copies of the bicep files and reference them inteamsapp.local.yml
.- Update
env/.env.local
with environment variables referenced inteamsapp.local.yml
.
Now you can run and debug your app with Teams Toolkit.
Learn more about Teams Toolkit's debugging process.
Integrating the remote provision, deploy, and publish process
You can customize Teams Toolkit's remote provision, deploy and publish process with teamsapp.yml
.
teamsapp.yml
Update - Update the provision, deploy, and publish lifecycles with actions that suits your existing application.
- Note: you can use
script
action to run any arbitrary commands.
Update environment variables
- Update the
.env.{envName}
and.env.{envName}.user
files with environment variable values referenced byteamsapp.yml
,appPackage/manifest.json
, Azure bicep files, and your code. - Teams Toolkit scaffolded project use the
dev
environment for remote by default. You can create new environments. Learn more about Teams Toolkit environments.