Hinzufügen einer Botfunktion zur Teams-App

Die folgenden Schritte helfen Ihnen beim Hinzufügen eines Bots zu einer Registerkarten-App:

• Erstellen einer Bot-App mit dem Microsoft 365 Agents Toolkit
• Konfigurieren der Botfunktion im App-Manifest
• Hinzufügen von Botcode zu Ihrem Projekt
• Einrichten einer lokalen Debugumgebung
• Bereitstellen der App in Azure

Erstellen einer Bot-App mit dem Agents Toolkit

Informationen zum Erstellen einer Bot-App mithilfe des Agents Toolkits (früher als Teams Toolkit bezeichnet) finden Sie unter Erstellen einer Bot-App mit Agents Toolkit.

Konfigurieren der Botfunktion im App-Manifest

Sie können die Botfunktion in der appPackage/manifest.json Datei konfigurieren. Weitere Informationen finden Sie unter App-Manifestschema.

Der folgende Codeausschnitt ist ein Beispiel:

    "bots": [
        {
            "botId": "${{BOT_ID}}",
            "scopes": [
                "personal",
                "team",
                "groupchat"
            ],
            "supportsFiles": false,
            "isNotificationOnly": false,
            "commandLists": [
                {
                    "scopes": [
                        "personal",
                        "team",
                        "groupchat"
                    ],
                    "commands": [
                        {
                            "title": "welcome",
                            "description": "Resend welcome card of this Bot"
                        },
                        {
                            "title": "learn",
                            "description": "Learn about Adaptive Card and Bot Command"
                        }
                    ]
                }
            ]
        }
    ]

Hinzufügen von Botcode zu Ihrem Projekt

1. Erstellen Sie einen bot/ Ordner in Ihrem Projekt, und kopieren Sie den Quellcode der Bot-App in den Ordner in Visual Studio Code. Die Ordnerstruktur Ihres Projekts sieht wie folgt aus:

       |-- .vscode/
       |-- appPackage/
       |-- env/
       |-- infra/
       |--public/
       |-- bot/           <!--bot source code-->
       |   |-- adaptiveCards/
       |   |-- index.ts
       |   |-- config.ts
       |   |-- teamsBot.ts
       |   |-- package.json
       |   |-- tsconfig.json
       |   |-- web.config
       |   |-- .webappignore
       |-- src/            <!--your current source code-->
       |   |-- app.ts
       |   |-- static/
       |   |-- views/
       |-- package.json
       |-- tsconfig.json
       |-- m365agents.local.yml
       |-- m365agents.yml
   

2. Organisieren Sie die Ordnerstruktur wie folgt neu:

   Tipp

   Verwenden Sie den Befehl npm init -y , um eine Stammdatei package.json zu erstellen.

       |-- .vscode/
       |-- appPackage/
       |-- env/
       |-- infra/
       |-- bot/            <!--bot source code-->
       |   |-- adaptiveCards/
       |   |-- index.ts
       |   |-- config.ts
       |   |-- teamsBot.ts
       |   |-- package.json
       |   |-- tsconfig.json
       |   |-- web.config
       |   |-- .webappignore
       |-- tab/           <!--move your current source code to a new sub folder-->
       |   |-- src/
       |   |   |-- app.ts
       |   |   |-- static/
       |   |   |-- views/
       |   |-- package.json
       |   |-- tsconfig.json
       |-- package.json <!--root package.json-->
       |-- m365agents.local.yml
       |-- m365agents.yml
   

3. Fügen Sie dem Stamm package.jsonden folgenden Code hinzu:

       "scripts": {
         "test": "echo \"Error: no test specified\" && exit 1",
         "install:bot": "cd bot && npm install",
         "install:tab": "cd tab && npm install",
         "install": "concurrently \"npm run install:bot\" \"npm run install:tab\"",
         "dev:bot": "cd bot && npm run dev",
         "start:tab": "cd tab && npm run start",
         "build:tab": "cd tab && npm run build",
         "build:bot": "cd bot && npm run build",
         "build": "concurrently \"npm run build:tab\" \"npm run build:bot\""
       },
       "dependencies": {
           "concurrently": "^7.6.0"
       },
   

   Hinweis

   In einem JavaScript-Projekt können Sie das Projekt ohne Ordner build ausführen. Sie müssen das build:bot Skript entfernen und das build Skript auf npm run build:tabaktualisieren.

Einrichten einer lokalen Debugumgebung

1. Aktualisieren Sie .vscode/tasks.json wie folgt:

   1. Fügen Sie drei neue Aufgaben hinzu: Start local tunnel, Start botund Start frontend.
   2. Aktualisieren Sie das Array der dependsOnStart application Aufgabe, um und Start frontendeinzuschließenStart bot.
   3. Konfigurieren Sie die cwd Option für Start bot und Start frontend. Diese Aktion ist erforderlich, da Sie den Code für die Registerkarte und den Bot zuvor in ihre jeweiligen Ordner verschoben haben, während Sie die Ordnerstruktur neu organisieren.
   4. Fügen Sie Start local tunnel dem Array der Start Teams App LocallydependsOn Aufgabe hinzu.

       "tasks":[
               {
                   // Start the local tunnel service to forward public URL to local port and inspect traffic.
                   // See https://aka.ms/teamsfx-tasks/local-tunnel for the detailed args definitions.
                   "label": "Start local tunnel",
                   "type": "teamsfx",
                   "command": "debug-start-local-tunnel",
                   "args": {
                       "type": "dev-tunnel",
                       "ports": [
                           {
                               "portNumber": 3978,
                               "protocol": "http",
                               "access": "public",
                               "writeToEnvironmentFile": {
                                   "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
                                   "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
                               }
                           }
                       ],
                       "env": "local"
                   },
                   "isBackground": true,
                   "problemMatcher": "$teamsfx-local-tunnel-watch"
               },
               {
                   "label": "Start bot",
                   "type": "shell",
                   "command": "npm run dev:teamsfx",
                   "isBackground": true,
                   "options": {
                       "cwd": "${workspaceFolder}/bot"
                   },
                   "problemMatcher": {
                       "pattern": [
                           {
                               "regexp": "^.*$",
                               "file": 0,
                               "location": 1,
                               "message": 2
                           }
                       ],
                       "background": {
                           "activeOnStart": true,
                           "beginsPattern": "[nodemon] starting",
                           "endsPattern": "restify listening to|Bot/ME service listening at|[nodemon] app crashed"
                       }
                   }
               },
               {
                  "label": "Start frontend",
                  "type": "shell",
                  "command": "npm run dev:teamsfx",
                  "isBackground": true,
                  "options": {
                       "cwd": "${workspaceFolder}/tab"
                   },
                   "problemMatcher": {
                       "pattern": {
                           "regexp": "^.*$",
                           "file": 0,
                           "location": 1,
                           "message": 2
                       },
                       "background": {
                           "activeOnStart": true,
                           "beginsPattern": ".*",
                           "endsPattern": "listening to|Compiled|Failed|compiled|failed"
                       }
                   }
               },
                {
                    "label": "Start application",
                    "dependsOn": [
                        "Start bot",
                        "Start frontend"
                    ]
                },
                {
                    "label": "Start Teams App Locally",
                    "dependsOn": [
                        "Validate prerequisites",
                        "Start local tunnel",
                        "Provision",
                        "Deploy",
                        "Start application"
                    ],
                    "dependsOrder": "sequence"
                },
       ]
   

2. Unter der m365agents.local.yml Datei:

   1. Fügen Sie unter provisiondie botAadApp/create Aktionen und botFramework/create hinzu.
   2. Aktualisieren Sie unter deployden Code der file/createOrUpdateEnvironmentFile Aktion.

    provision:
      - uses: botAadApp/create
        with:
          # The Microsoft Entra application's display name
          name: bot-${{TEAMSFX_ENV}}
        writeToEnvironmentFile:
          # The Microsoft Entra application's client id created for bot.
          botId: BOT_ID
          # The Microsoft Entra application's client secret created for bot.
          botPassword: SECRET_BOT_PASSWORD 
   
      # Create or update the bot registration on dev.botframework.com
      - uses: botFramework/create
        with:
          botId: ${{BOT_ID}}
          name: bot
          messagingEndpoint: ${{BOT_ENDPOINT}}/api/messages
          description: ""
          channels:
            - name: msteams
    deploy:
      - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
        with:
          target: ./tab/.localConfigs
          envs:
            BROWSER: none
            HTTPS: true
            PORT: 53000
            SSL_CRT_FILE: ${{SSL_CRT_FILE}}
            SSL_KEY_FILE: ${{SSL_KEY_FILE}}
   
      - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
        with:
          target: ./bot/.localConfigs
          envs:
            BOT_ID: ${{BOT_ID}}
            BOT_PASSWORD: ${{SECRET_BOT_PASSWORD}}
   

   Weitere Informationen finden Sie unter Beispiel-App.

3. Wählen Sie unter Ausführen und Debuggendie Option Debuggen (Edge) oder Debuggen (Chrome) aus.

4. Wählen Sie F5 aus, um Ihre Teams-App lokal zu debuggen und eine Vorschau anzuzeigen.

Bereitstellen der App in Azure

1. Kopieren Sie den botRegistration/ Ordner aus dem Bot in infra/.

2. Fügen Sie der Datei den azure.bicep folgenden Code hinzu:

    param resourceBaseName2 string
    param webAppName2 string = resourceBaseName2
    @maxLength(42)
    param botDisplayName string
    @description('Required when create Azure Bot service')
    param botAadAppClientId string
   
    @secure()
    @description('Required by Bot Framework package in your bot project')
    param botAadAppClientSecret string
    resource webApp2 'Microsoft.Web/sites@2021-02-01' = {
      kind: 'app'
      location: location
      name: webAppName2
      properties: {
        serverFarmId: serverfarm.id
        httpsOnly: true
        siteConfig: {
          alwaysOn: true
          appSettings: [
            {
              name: 'WEBSITE_RUN_FROM_PACKAGE'
              value: '1' // Run Azure APP Service from a package file
            }
            {
              name: 'WEBSITE_NODE_DEFAULT_VERSION'
              value: '~18' // Set NodeJS version to 18.x for your site
            }
            {
              name: 'RUNNING_ON_AZURE'
              value: '1'
            }
            {
              name: 'BOT_ID'
              value: botAadAppClientId
            }
            {
              name: 'BOT_PASSWORD'
              value: botAadAppClientSecret
            }
          ]
          ftpsState: 'FtpsOnly'
        }
      }
    }
   
    // Register your web service as a bot with the Bot Framework
    module azureBotRegistration './botRegistration/azurebot.bicep' = {
      name: 'Azure-Bot-registration'
      params: {
        resourceBaseName: resourceBaseName
        botAadAppClientId: botAadAppClientId
        botAppDomain: webApp2.properties.defaultHostName
        botDisplayName: botDisplayName
      }
    }
   
    // The output will be persisted in .env.{envName}. Visit https://aka.ms/teamsfx-actions/arm-deploy for more details.
    output BOT_AZURE_APP_SERVICE_RESOURCE_ID string = webApp2.id
    output BOT_DOMAIN string = webApp2.properties.defaultHostName
   

3. Aktualisieren Sie die Datei mit dem folgenden Code, um sicherzustellen, dass die azure.parameters.json erforderlichen Parameter richtig festgelegt sind:

    {
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "resourceBaseName": {
        "value": "tab${{RESOURCE_SUFFIX}}"
      },
      "webAppSku": {
        "value": "B1"
      },
      "botAadAppClientId": {
        "value": "${{BOT_ID}}"
      },
      "botAadAppClientSecret": {
        "value": "${{SECRET_BOT_PASSWORD}}"
      },
      "botDisplayName": {
        "value": "bot"
      },
      "resourceBaseName2":{
        "value": "bot${{RESOURCE_SUFFIX}}"
      }
    }
    }
   

4. Unter der m365agents.yml Datei:

   1. Fügen Sie unter provisiondie botAadApp/create Aktion hinzu. Weitere Informationen finden Sie unter Beispiel-App.
   2. Fügen Sie im deploy Abschnitt den folgenden Code hinzu:

    deploy:
      - uses: cli/runNpmCommand # Run npm command
        with:
          args: install
      - uses: cli/runNpmCommand # Run npm command
        with:
          args: run build
      # Deploy bits to Azure Storage Static Website
      - uses: azureAppService/zipDeploy
        with:
          workingDirectory: ./tab
          # Deploy base folder
          artifactFolder: .
          # Ignore file location, leave blank will ignore nothing
          ignoreFile: .webappignore
          # The resource id of the cloud resource to be deployed to.
          # This key will be generated by arm/deploy action automatically.
          # You can replace it with your existing Azure Resource id
          # or add it to your environment variable file.
          resourceId: ${{TAB_AZURE_APP_SERVICE_RESOURCE_ID}}
      - uses: azureAppService/zipDeploy
        with:
          workingDirectory: ./bot
          # Deploy base folder
          artifactFolder: .
          # Ignore file location, leave blank will ignore nothing
          ignoreFile: .webappignore
          # The resource id of the cloud resource to be deployed to.
          # This key will be generated by arm/deploy action automatically.
          # You can replace it with your existing Azure Resource id
          # or add it to your environment variable file.
          resourceId: ${{BOT_AZURE_APP_SERVICE_RESOURCE_ID}}
   

5. Wechseln Sie zu Befehlspalette anzeigen>... oder drücken Sie STRG+UMSCHALT+P.

6. Geben Sie ein Teams: Provision , um den Bicep auf Azure anzuwenden.

7. Geben Sie ein Teams: Deploy , um Ihren Registerkarten-App-Code in Azure bereitzustellen.

8. Wählen Sie unter Ausführen und Debuggendie Option Remote starten (Edge) oder Remote starten (Chrome) aus.

9. Wählen Sie F5 aus, um Ihre Teams-App zu debuggen und eine Vorschau anzuzeigen.

Sie können die Botfunktion ganz einfach zu einer Nachrichtenerweiterungs-App hinzufügen, da Nachrichtenerweiterungen auf Bot Framework basieren.

Die folgenden Schritte helfen Ihnen beim Hinzufügen der Botfunktion zu einer Nachrichtenerweiterungs-App:

• Erstellen einer Bot-App mit dem Agents Toolkit
• Manifestdatei aktualisieren
• Hinzufügen von Botcode zum Projekt

Erstellen einer Bot-App mit dem Agents Toolkit

Informationen zum Erstellen einer Bot-App mit agents Toolkit finden Sie unter Erstellen einer neuen Teams-Bot-App.

Manifestdatei aktualisieren

Sie können die Botfunktion in der appPackage/manifest.json Datei konfigurieren. Weitere Informationen finden Sie unter App-Manifestschema.

Der folgende Codeausschnitt ist ein Beispiel:

 "bots": [
     {
         "botId": "${{BOT_ID}}",
         "scopes": [
             "personal",
             "team",
             "groupchat"
         ],
         "supportsFiles": false,
         "isNotificationOnly": false,
         "commandLists": [
             {
                 "scopes": [
                     "personal",
                     "team",
                     "groupchat"
                 ],
                 "commands": [
                     {
                         "title": "welcome",
                         "description": "Resend welcome card of this Bot"
                     },
                     {
                         "title": "learn",
                         "description": "Learn about Adaptive Card and Bot Command"
                     }
                 ]
             }
         ]
     }
 ]

Hinzufügen von Botcode zum Projekt

1. Ihre Nachrichtenerweiterungs-App enthält eine Klasse, die erweitert TeamsActivityHandler. Kopieren Sie Ihren konfigurierten Botcode aus der Bot-App in diese Klasse in Visual Studio Code. Der folgende Code ist ein Beispiel für eine Nachrichtenerweiterung, die Funktionen aus einer Bot-App enthält, die im Agents Toolkit erstellt wurde:

      public class YourHandler extends TeamsActivityHandler{
   
        // bot code
        constructor(){
          super();
          this.likeCountObj = { likeCount: 0 };
          this.onMessage(async (context, next) => {});
          this.onMembersAdded(async (context, next) => {});
        }
        async onAdaptiveCardInvoke(context: TurnContext,
    invokeValue: AdaptiveCardInvokeValue):  Promise<AdaptiveCardInvokeResponse> {};
   
        /**
         * your own message extension code
        */
      }
   

2. Wechseln Sie zu Befehlspalette anzeigen>... oder drücken Sie STRG+UMSCHALT+P.

3. Geben Sie ein Teams: Provision , um den Bicep auf Azure anzuwenden.

4. Geben Sie ein Teams: Deploy , um Ihren Registerkarten-App-Code in Azure bereitzustellen.

5. Wählen Sie unter Ausführen und Debuggendie Option Remote starten (Edge) oder Remote starten (Chrome) aus.

6. Wählen Sie F5 aus, um Ihre Teams-App zu debuggen und eine Vorschau anzuzeigen.