Hinzufügen der Nachrichtenerweiterungsfunktion zur Teams-App

Führen Sie die folgenden Schritte aus, um einer Registerkarten-App eine Nachrichtenerweiterung hinzuzufügen:

1. Erstellen einer Nachrichtenerweiterungs-App mit dem Microsoft Teams-Toolkit
2. Konfigurieren der Nachrichtenerweiterung im App-Manifest
3. Hinzufügen von Nachrichtenerweiterungscode zu Ihrem Projekt
4. Einrichten einer lokalen Debugumgebung
5. Bereitstellen Ihrer App in Azure

Erstellen einer Nachrichtenerweiterungs-App mit dem Microsoft Teams-Toolkit

Informationen zum Erstellen einer Nachrichtenerweiterungs-App mit teams Toolkit finden Sie unter Erstellen einer Nachrichtenerweiterungs-App mit Teams Toolkit.

Konfigurieren der Nachrichtenerweiterung im App-Manifest

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

Der folgende Codeausschnitt ist ein Beispiel:

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
               ],
               "description": "Test command to run query",
               "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
                }
            }
        ]
    }
]

Hinzufügen von Nachrichtenerweiterungscode zu Ihrem Projekt

1. Erstellen Sie einen bot/ Ordner in Ihrem Registerkartenprojekt in Visual Studio Code. Kopieren Sie den Quellcode der Nachrichtenerweiterungs-App in den Ordner. Die Ordnerstruktur Ihres Projekts sieht wie folgt aus:

   |--.vscode/
   |--appPackage/
   |--env/
   |--infra/
   |--public/
   |--bot/           <!--message extension source code-->
   |   |--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
   |--teamsapp.local.yml
   |--teamsapp.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/            <!--message extension source code-->
      |--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-->
   |--teamsapp.local.yml
   |--teamsapp.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 teamsapp.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 Ihrer App in Azure

1. Kopieren Sie den Ordner, botRegistration/ und fügen Sie unter hinzu 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 teamsapp.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 Nachrichtenerweiterungsfunktion ganz einfach zu einer Bot-App hinzufügen, da Nachrichtenerweiterungen auf Bot Framework basieren.

Führen Sie die folgenden Schritte aus, um einer Bot-App eine Nachrichtenerweiterung hinzuzufügen:

1. Erstellen einer Nachrichtenerweiterungs-App mithilfe des Teams-Toolkits
2. Konfigurieren der Nachrichtenerweiterung im App-Manifest
3. Hinzufügen von Nachrichtenerweiterungscode zum Projekt

Erstellen einer Nachrichtenerweiterung mithilfe des Teams-Toolkits

Informationen zum Erstellen einer Nachrichtenerweiterungs-App finden Sie unter Erstellen einer Nachrichtenerweiterungs-App mit dem Teams-Toolkit.

Konfigurieren der Nachrichtenerweiterung im App-Manifest

Sie können die Nachrichtenerweiterungsfunktion in appPackage/manifest.jsonkonfigurieren. Weitere Informationen finden Sie unter App-Manifestschema.

Der folgende Codeausschnitt ist ein Beispiel:

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                   {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
                ],
                "description": "Test command to run query",
                "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
               }
            }
        ]
    }
]

Hinzufügen von Nachrichtenerweiterungscode zum Projekt

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

     class YourHandler extends TeamsActivityHandler {
     /**
      * your own code
      */
     //message extension code
     // Action.
     public async handleTeamsMessagingExtensionSubmitAction(
       context: TurnContext,
       action: any
     ): Promise<any> {}
     // Search.
     public async handleTeamsMessagingExtensionQuery(
       context: TurnContext,
       query: any
     ): Promise<any> {}
     public async handleTeamsMessagingExtensionSelectItem(
       context: TurnContext,
       obj: any
     ): Promise<any> {}
     // Link Unfurling.
     public async handleTeamsAppBasedLinkQuery(
       context: TurnContext,
       query: any
     ): Promise<any> {}
   }
   async function createCardCommand(
     context: TurnContext,
     action: MessagingExtensionAction
   ): Promise<MessagingExtensionResponse> {}
   async function shareMessageCommand(
     context: TurnContext,
     action: MessagingExtensionAction
   ): Promise<MessagingExtensionResponse> {}
   

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.