You may want to change the out-of-box provision behavior provided by the tooling. This section introduces what kind of customization you can achieve.

You can add following configuration snippet to .fx/configs/config.{your_env_name}.json to use an Microsoft Entra app created by yourself for your Teams app. You can follow https://aka.ms/teamsfx-existing-aad-doc to create an Microsoft Entra app that can be used here.

"auth": {
    "clientId": "<your Microsoft Entra app client id",
    "clientSecret": "{{$env.ENV_NAME_THAT_STORES_YOUR_SECRET}}",
    "objectId": "<your Microsoft Entra app object id>",
    "accessAsUserScopeId": "<id of the access_as_user scope>"
}

After added above snippet, add your secret to related environment variable so the tooling can resolve the actual secret during provision.

Note: You should not share one Microsoft Entra app in multiple environments. If you do not have permission to update the Microsoft Entra app, you will get a warning with instructions about how to manually update the Microsoft Entra app. Please follow the instructions to update your Microsoft Entra app after provision.

You can add following configuration snippet to .fx/configs/config.{your_env_name}.json file to use an Microsoft Entra app created by yourself for your bot.

"bot": {
    "appId": "<your Microsoft Entra app client id>",
    "appPassword": "{{$env.ENV_NAME_THAT_STORES_YOUR_SECRET}}"
}

After added above snippet, add your secret to related environment variable so the tooling can resolve the actual secret during provision.

Note: You should not share one Microsoft Entra app in multiple environments.

Sometimes you may get insufficient permission error when the tool tries to add user to SQL database. You can add following configuration snippet to .fx/configs/config.{your_env_name}.json file to skip adding SQL database user.

"skipAddingSqlUser": true

Before provision, the tool will ask you if you want to create a new resource group or use an existing one. You can provide a new resource group name or choose an existing one in this step.

The tooling uses ARM template to define Azure resources. The ARM template is a set of bicep files that defines the infrastructure and configuration for your project. You can customize Azure resources being created by modifying the ARM template. Visit bicep document to learn more about how to use bicep to author ARM template.

You have two ways to customize Azure resources being created: customizing the parameter files and customizing the bicep files.

The tooling provides a set of predefined parameters for you to customize the Azure resources. The parameter files are located at .fx/configs/azure.parameters.{your_env_name}.json and all the available parameters are defined in the provisionParameters property. It's preferred to customize the parameter files if the predefined parameters satisfies your requirement.

Here's a list of predefined parameters available:

In the meanwhile, following parameters are available with values populated during provision. If you want to change value of these parameters, you can delete the placeholder and fill your expected value to it directly. The purpose of these placeholders is to ensure we can create new resources for you when you created a new environment. The actual values are resolved from .fx/states/state.{your_env_name}.json.

Some times you may not want to hardcode the values in parameter files. For example, when the value is a secret. The parameter files support referencing the values from environment variables. You can use syntax {{$env.YOUR_ENV_VARIABLE_NAME}} in parameter values to tell the tooling that the value needs to be resolved from current environment variable.

Following example will read the value of mySelfHostedDbConnectionString parameter from environment variable DB_CONNECTION_STRING:

...
    "mySelfHostedDbConnectionString": "{{$env.DB_CONNECTION_STRING}}"
...

This this example, I will specify another name contosoteamsappapi for Function App instance instead of using the default name.

The steps are:

1. Open .fx/configs/azure.parameters.{env}.json for your current environment.
2. Add a new property functionAppName to the value of parameter provisionParameters.
3. Fill "contosoteamsappapi" as value of functionAppName
4. The final parameter file will looks like following

   {
       "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
       "contentVersion": "1.0.0.0",
       "parameters": {
           "provisionParameters": {
           "value": {
               "functionAppName": "contosoteamsappapi"
               ...
               }
           }
       }
   }
   

Note: If you already provisioned the environment, specifying the name will create a new Function App instance for you, instead of renaming the instance created previously.

If the predefined parameters does not satisfy your requirement, you can customize the ARM template under templates/azure folder. For example, you can customize the ARM template to create some additional Azure resources for your app. This is an advance scenario and requires you have basic knowledge of bicep language which is used to author ARM template. You can get started with bicep at bicep documentation.

Note: the ARM template is shared by all environments. You can use conditional deployment if the provision behavior various between environments.

The ARM template located at templates/azure contains following files

Note: teamsfx/xxx.bicep will be regenerated when you add resources / capabilities to your project. That's why it's marked as not customizable. If you realy have requirement to modify these bicep files, go ahead. We suggest using Git to track your changes to teamsfx/xxx.bicep files so you won't lose your changes when adding resources / capabilities.

To ensure the TeamsFx tooling functions properly, please ensure your customized ARM template satisfies following requirement. If you uses other tooling for further development, you can ignore these requirement.

1. Keep the folder structure and file name unchanged. The tool may append new content to existing files when you adds more resources / capabilities to your project.
2. Keep the name of auto generated parameters as well as its property names unchanged. The auto generated parameters may be used when you adds more resources / capabilities to your project.
3. Keep the output of auto generated ARM template unchanged. You can add additional outputs to ARM template. The output will be persisted to .fx/states/state.{env}.json and used in other features like deploy, validate manifest file, etc.

Consider the scenario, you want to add Azure Storage to your Azure Function backend to store some blob data. There is no auto flow to update the bicep template with Azure Storage support. However, you can edit the bicep file and add the resource. The steps are as follows

1. Create a tab project

2. Add a function to the project. You can visit Add Resources to learn more about adding resources.

3. Declare the new Storage Account in ARM template. For simplify, we will declare the resource at templates/azure/provision/function.bicep directly. You're free to declare the resources in other places.

   var applicationStorageAccountName = 'myapp${uniqueString(resourceGroup().id)}'
   resource applicationStorageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
       name: applicationStorageAccountName
       location: resourceGroup().location
       kind: 'Storage'
       sku: {
           name: 'Standard_LRS'
       }
   }
   

4. Update the Azure Function App Settings with Azure Storage connection string in templates/azure/provision/function.bicep, which is the same file in step 3. Add following snippet to functionApp resource's appSettings array.

   {
       name: 'MyAppStorageAccountConnectionString'
       value: 'DefaultEndpointsProtocol=https;AccountName=${applicationStorageAccount.name};AccountKey=${listKeys(applicationStorageAccount.id, '2021-06-01').key1}'
   }
   

5. Now your can update your function with Azure Storage output bindings.