@microsoft/teamsfx 2.1.1-alpha.121c64dd9.0 → 2.1.1-alpha.169762110.0

package/README.md

@@ -23,7 +23,7 @@ Please check the [README](https://github.com/OfficeDev/TeamsFx/blob/main/package
 
 - Node.js version 10.x.x or higher
 - A project created by the Teams Toolkit VS Code extension or `teamsfx` CLI tool.
-- If your project has installed `botbuilder` related [packages](https://github.com/Microsoft/botbuilder-js#packages) as dependencies, ensure they are of the same version and the version `>= 4.15.0`. ([Issue - all of the BOTBUILDER packages should be the same version](https://github.com/BotBuilderCommunity/botbuilder-community-js/issues/57#issuecomment-508538548))
+- If your project has installed `botbuilder` related [packages](https://github.com/Microsoft/botbuilder-js#packages) as dependencies, ensure they are of the same version and the version `>= 4.18.0`. ([Issue - all of the BOTBUILDER packages should be the same version](https://github.com/BotBuilderCommunity/botbuilder-community-js/issues/57#issuecomment-508538548))
 
 ### Install the `@microsoft/teamsfx` package
 
@@ -36,6 +36,7 @@ npm install @microsoft/teamsfx
 ### Scenarios
 
 TeamsFx SDK is built to be used in browser and NodeJS environment. Common scenarios include:
+
 - Teams tab application
 - Azure Function
 - Teams bot
@@ -78,26 +79,30 @@ const profile = await graphClient.api("/users/{object_id_of_another_people}").ge
 ## Core Concepts & Code Structure
 
 ### TeamsFx class
+
 `TeamsFx` class instance reads all TeamsFx settings from environment variables by default. You can also set customized configuration values to override the default values. Please check [Override configuration](#override-configuration) for details.
 
 When creating a TeamsFx instance, you also need to specify the identity type. There are 2 identity types:
 
 #### User Identity
+
 Using `new TeamsFx(IdentityType.User)` means the application will be authenticated as current Teams user. This one is the default choice. You need to call `TeamsFx:setSsoToken()` when you use user identity in NodeJS environment(without browser).
 
 You can use `TeamsFx:getUserInfo()` to get user's basic information.
 `TeamsFx:login()` is used to let user perform consent process if you want to use SSO to get access token for certain OAuth scopes.
 
 #### Application Identity
+
 Using `new TeamsFx(IdentityType.App)` means the application will be authenticated as an application. The permission usually need administrator's approval.
 
 `TeamsFx:getCredential()` provides credential instances automatically corresponding to identity type:
+
 - User Identity: It means that you can access resources on behalf of current Teams user.
 - App Identity: It means that you are acting as a managed app identity which usually need admin consent for resources.
 
 ### Credential
 
-//Developers should choose identity type when initializing TeamsFx. SDK provides 2 types: User and App.
+Developers should choose identity type when initializing TeamsFx. SDK provides 2 types: User and App.
 After developer has specified the identity type when initializing TeamsFx, SDK uses different kinds of credential class to represent the identity and get access token by corresponding auth flow.
 
 There are 3 credential classes that are used to help simplifying authentication. They are located under [credential](src/credential) folder.
@@ -106,16 +111,19 @@ Credential classes implements `TokenCredential` interface that is broadly used i
 Here's the corresponding scenarios that each credential class targets.
 
 #### User Identity in browser environment
+
 `TeamsUserCredential` represents Teams current user's identity. Using this credential will request user consent at the first time. It leverages the Teams SSO and On-Behalf-Of flow to do token exchange. SDK uses this credential when developer choose "User" identity in browser environment.
 
 Required configuration: initiateLoginEndpoint, clientId.
 
 #### User Identity in NodeJS environment
+
 `OnBehalfOfUserCredential` uses On-Behalf-Of flow and need Teams ssoToken. It's designed to be used in Azure Function or Bot scenarios. SDK uses this credential when developer choose "User" identity in NodeJS environment.
 
 Required configuration: authorityHost, tenantId, clientId, clientSecret / certificateContent.
 
 #### Application Identity in NodeJS environment
+
 `AppCredential` represents the application identity. It is usually used when user is not involved like time-triggered automation job. SDK uses this credential when developer choose "App" identity in NodeJS environment.
 
 Required configuration: tenantId, clientId, clientSecret / certificateContent.
@@ -133,12 +141,15 @@ Required configuration: initiateLoginEndpoint, tenantId, clientId, applicationId
 TeamsFx SDK provides several helper functions to ease the configuration for third-party libraries. They are located under [core](src/core) folder.
 
 #### Microsoft Graph Service
+
 `createMicrosoftGraphClient` and `MsGraphAuthProvider` help to create authenticated Graph instance.
 
 #### SQL
-`getTediousConnectionConfig` returns a tedious connection config.
+
+`getTediousConnectionConfig` returns a tedious connection config. This API is now deprecated, we recommend you compose your own Tedious configuration for better flexibility.
 
 Required configuration:
+
 - sqlServerEndpoint, sqlUsername, sqlPassword if you want to use user identity
 - sqlServerEndpoint, sqlIdentityId if you want to use MSI identity
 
@@ -209,7 +220,8 @@ const credential = teamsfx.getCredential();
 // Create an API client that uses SSO token to authenticate requests
 const apiClient = createApiClient(
   teamsfx.getConfig("apiEndpoint"),
-  new BearerTokenAuthProvider(async ()=> (await credential.getToken(""))!.token));
+  new BearerTokenAuthProvider(async () => (await credential.getToken(""))!.token)
+);
 // Call API hosted in Azure Functions on behalf of user
 const response = await apiClient.get("/api/" + functionName);
 ```
@@ -219,6 +231,8 @@ const response = await apiClient.get("/api/" + functionName);
 Use `tedious` library to access SQL and leverage `DefaultTediousConnectionConfiguration` that manages authentication.
 Apart from `tedious`, you can also compose connection config of other SQL libraries based on the result of `sqlConnectionConfig.getConfig()`.
 
+The `tedious` library is now deprecated, we recommend you compose your own Tedious configuration for better flexibility.
+
 ```ts
 // Equivalent to:
 // const sqlConnectConfig = new DefaultTediousConnectionConfiguration({
@@ -243,7 +257,7 @@ connection.on("connect", (error) => {
 
 ```ts
 const teamsfx = new TeamsFx(IdentityType.App, {
-  certificateContent: "The content of a PEM-encoded public/private key certificate"
+  certificateContent: "The content of a PEM-encoded public/private key certificate",
 });
 const token = teamsfx.getCredential().getToken();
 ```
@@ -293,15 +307,18 @@ const teamsfx = new TeamsFx();
 
 // Create an API Key auth provider. Following auth providers are also available:
 // BearerTokenAuthProvider, BasicAuthProvider, CertificateAuthProvider
-const authProvider = new ApiKeyProvider("your_api_key_name", 
+const authProvider = new ApiKeyProvider(
+  "your_api_key_name",
   teamsfx.getConfig("YOUR_API_KEY_VALUE"), // This reads the value of YOUR_API_KEY_VALUE environment variable
-  ApiKeyLocation.Header);
+  ApiKeyLocation.Header
+);
 
 // Create an API client using above auth provider
 // You can also implement AuthProvider interface and use it here
 const apiClient = createApiClient(
   teamsfx.getConfig("YOUR_API_ENDPOINT"), // This reads YOUR_API_ENDPOINT environment variable
-  authProvider);
+  authProvider
+);
 
 // Send a GET request to "relative_api_path"
 const response = await apiClient.get("relative_api_path");
@@ -352,36 +369,38 @@ setLogFunction((level: LogLevel, message: string) => {
 });
 ```
 
-
 ### Override configuration
+
 You can pass custom config when creating `TeamsFx` instance to override default configuration or set required fields when environment variables are missing.
 
 - If you have created tab project using VS Code toolkit, the following config values will be used from pre-configured environment variables:
-  * authorityHost (REACT_APP_AUTHORITY_HOST)
-  * tenantId (REACT_APP_TENANT_ID)
-  * clientId (REACT_APP_CLIENT_ID)
-  * initiateLoginEndpoint (REACT_APP_START_LOGIN_PAGE_URL)
-  * applicationIdUri (REACT_APP_START_LOGIN_PAGE_URL)
-  * apiEndpoint (REACT_APP_FUNC_ENDPOINT)
-  * apiName (REACT_APP_FUNC_NAME)
+
+  - authorityHost (REACT_APP_AUTHORITY_HOST)
+  - tenantId (REACT_APP_TENANT_ID)
+  - clientId (REACT_APP_CLIENT_ID)
+  - initiateLoginEndpoint (REACT_APP_START_LOGIN_PAGE_URL)
+  - applicationIdUri (REACT_APP_START_LOGIN_PAGE_URL)
+  - apiEndpoint (REACT_APP_FUNC_ENDPOINT)
+  - apiName (REACT_APP_FUNC_NAME)
 
 - If you have created Azure Function / Bot project using VS Code toolkit, the following config values will be used from pre-configured environment variables:
-  * initiateLoginEndpoint (INITIATE_LOGIN_ENDPOINT)
-  * authorityHost (M365_AUTHORITY_HOST)
-  * tenantId (M365_TENANT_ID)
-  * clientId (M365_CLIENT_ID)
-  * clientSecret (M365_CLIENT_SECRET)
-  * applicationIdUri (M365_APPLICATION_ID_URI)
-  * apiEndpoint (API_ENDPOINT)
-  * sqlServerEndpoint (SQL_ENDPOINT)
-  * sqlUsername (SQL_USER_NAME)
-  * sqlPassword (SQL_PASSWORD)
-  * sqlDatabaseName (SQL_DATABASE_NAME)
-  * sqlIdentityId (IDENTITY_ID)
+  - initiateLoginEndpoint (INITIATE_LOGIN_ENDPOINT)
+  - authorityHost (M365_AUTHORITY_HOST)
+  - tenantId (M365_TENANT_ID)
+  - clientId (M365_CLIENT_ID)
+  - clientSecret (M365_CLIENT_SECRET)
+  - applicationIdUri (M365_APPLICATION_ID_URI)
+  - apiEndpoint (API_ENDPOINT)
+  - sqlServerEndpoint (SQL_ENDPOINT)
+  - sqlUsername (SQL_USER_NAME)
+  - sqlPassword (SQL_PASSWORD)
+  - sqlDatabaseName (SQL_DATABASE_NAME)
+  - sqlIdentityId (IDENTITY_ID)
 
 ## How to fix the breaking change if upgraded from previous SDK version
 
 If you are using the version of SDK that has `loadConfiguration()`, you can follow these steps to upgrade to the latest SDK version.
+
 1. Remove `loadConfiguration()` and pass customized settings using `new TeamsFx(IdentityType.User, { ...customConfig })`.
 2. Replace `new TeamsUserCredential()` with `new TeamsFx()`.
 3. Replace `new M365TenantCredential()` with `new TeamsFx(IdentityType.App)`.
@@ -390,6 +409,29 @@ If you are using the version of SDK that has `loadConfiguration()`, you can foll
 
 Also see [TeamsFx class](#teamsfx-class) for furthur description.
 
+## How to use SDK implemented with `CloudAdapter`
+
+From `botbuilder@4.16.0`, `BotFrameworkAdapter` is deprecated, and `CloudAdapter` is recommended to be used instead. You can import `ConversationBot` from `BotBuilderCloudAdapter` to use the latest SDK implemented with `CloudAdapter`.
+
+```ts
+const { BotBuilderCloudAdapter } = require("@microsoft/teamsfx");
+const ConversationBot = BotBuilderCloudAdapter.ConversationBot;
+
+const commandBot = new ConversationBot({
+  // The bot id and password to create CloudAdapter.
+  // See https://aka.ms/about-bot-adapter to learn more about adapters.
+  adapterConfig: {
+    MicrosoftAppId: config.botId,
+    MicrosoftAppPassword: config.botPassword,
+    MicrosoftAppType: "MultiTenant",
+  },
+  command: {
+    enabled: true,
+    commands: [new HelloWorldCommandHandler()],
+  },
+});
+```
+
 ## Next steps
 
 Please take a look at the [Samples](https://github.com/OfficeDev/TeamsFx-Samples) project for detailed examples on how to use this library.