Erstellen einer Nachrichtenerweiterung
In dieser Lerneinheit erfahren Sie, wie Sie eine Nachrichtenerweiterung erstellen. Außerdem erfahren Sie, wie Sie Ihre Nachrichtenerweiterung in Microsoft Teams mithilfe des Teams-Toolkits ausführen und debuggen.
Zum Erstellen einer Nachrichtenerweiterung benötigen Sie die folgenden Komponenten:
- Azure Bot-Ressource zum Registrieren Ihres Webdiensts als Bot bei Bot Framework
- Webdienst zum Verarbeiten von Benutzerinteraktionen mit der Nachrichtenerweiterung
- App-Manifest zum Definieren der Nachrichtenerweiterungsfunktionen in Microsoft Teams
Konfigurieren einer Azure Bot-Ressource
Die Azure Bot-Ressource wird verwendet, um Ihren Webdienst als Bot beim Bot Framework zu registrieren. Zum Erstellen einer Azure Bot-Ressource ist eine Microsoft Entra App-Registrierung erforderlich. Die App-Registrierung bietet eine sichere Möglichkeit zum Authentifizieren und Autorisieren Ihres Bots. Der Webdienst verwendet die Microsoft Entra Anmeldeinformationen für die App-Registrierung, um sich beim Botdienst zu authentifizieren.
Der folgende Codeausschnitt zeigt, wie Sie eine Azure Bot-Ressource mit Bicep erstellen:
resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
kind: 'azurebot'
location: 'global'
name: 'botService'
properties: {
displayName: 'Bot Service'
endpoint: 'https://webservice.contoso.com/api/messages'
msaAppId: '00000000-0000-0000-0000-000000000000'
}
sku: {
name: botServiceSku
}
}
Die Endpunkteigenschaft gibt den Messagingendpunkt an, der für den Webdienst verfügbar gemacht wird, den der Botdienst zum Senden von Anforderungen verwendet, wenn ein Benutzer mit der Nachrichtenerweiterung interagiert. Die msaAppId-Eigenschaft gibt die Microsoft Entra App-Registrierungs-ID an, die zum Authentifizieren des Botdiensts beim Webdienst verwendet wird.
Kanäle werden verwendet, um den Botdienst mit Messagingplattformen wie Microsoft Teams, Slack, Facebook Messenger und mehr zu verbinden.
Der folgende Codeausschnitt zeigt, wie Sie die Microsoft Teams- und Microsoft 365-Kanäle (Outlook und Microsoft 365 Copilot) in der Azure Bot-Ressource konfigurieren:
resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
parent: botService
location: 'global'
name: 'MsTeamsChannel'
properties: {
channelName: 'MsTeamsChannel'
}
}
resource botServiceM365ExtensionsChannel 'Microsoft.BotService/botServices/channels@2022-06-15-preview' = {
parent: botService
location: 'global'
name: 'M365Extensions'
properties: {
channelName: 'M365Extensions'
}
}
Konfigurieren des Webdiensts
Der Webdienst ist eine Web-App, die den Nachrichtenerweiterungscode enthält. Der Webdienst ist für die Verarbeitung von Benutzerinteraktionen mit der Nachrichtenerweiterung verantwortlich und verwendet das Bot Framework SDK für die Kommunikation mit dem Botdienst.
Um Benutzerinteraktionen zu verarbeiten, implementieren Sie Folgendes:
- Einen Messagingendpunkt
- Botadapter
- Ein Botaktivitätshandler
Der Messagingendpunkt wird verwendet, um Anforderungen vom Botdienst zu empfangen. Der Messagingendpunkt wird im Webdienst verfügbar gemacht und übergibt die Anforderungen zur Verarbeitung an den Botadapter.
Der folgende Codeausschnitt zeigt, wie Der Messagingendpunkt konfiguriert wird:
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
private readonly IBotFrameworkHttpAdapter Adapter;
private readonly IBot Bot;
public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
{
Adapter = adapter;
Bot = bot;
}
[HttpPost, HttpGet]
public async Task PostAsync()
{
await Adapter.ProcessAsync(Request, Response, Bot);
}
}
Der Botadapter wird verwendet, um den Botdienst mit dem Webdienst zu verbinden. Der Botadapter ist für die Verarbeitung eingehender Anforderungen vom Botdienst und das Aufrufen des Botaktivitätshandlers verantwortlich. Der Webdienst authentifiziert sich beim Botdienst mithilfe der Anmeldeinformationen für die Microsoft Entra App-Registrierung, die zum Registrieren der Azure Bot-Ressource beim Bot Framework verwendet werden.
Der folgende Codeausschnitt zeigt, wie Sie den Botadapter im Webdienst konfigurieren:
// Create the Bot Framework Authentication to be used with the Bot Adapter.
var config = builder.Configuration.Get<ConfigOptions>();
builder.Configuration["MicrosoftAppType"] = "MultiTenant";
builder.Configuration["MicrosoftAppId"] = config.BOT_ID;
builder.Configuration["MicrosoftAppPassword"] = config.BOT_PASSWORD;
builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
// Create the Bot Framework Adapter with error handling enabled.
builder.Services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
// Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
builder.Services.AddTransient<IBot, SearchApp>();
Um die Benutzersuchabfrage zu verarbeiten und Suchergebnisse zurückzugeben, implementieren Sie einen Bot-Aktivitätshandler, der von der TeamsActivityHandler-Klasse erbt, die vom Bot Framework SDK bereitgestellt wird, und überschreiben Sie die OnTeamsMessagingExtensionQueryAsync-Methode .
Der folgende Codeausschnitt zeigt, wie Sie den Bot-Aktivitätshandler im Webdienst konfigurieren:
public class SearchApp : TeamsActivityHandler
{
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
var text = query?.Parameters?[0]?.Value as string ?? string.Empty;
var card = await File.ReadAllTextAsync(Path.Combine(".", "Resources", "card.json"), cancellationToken);
var template = new AdaptiveCards.Templating.AdaptiveCardTemplate(card);
return new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "result",
AttachmentLayout = "list",
Attachments = [
new MessagingExtensionAttachment
{
ContentType = AdaptiveCard.ContentType,
Content = JsonConvert.DeserializeObject(template.Expand(new { text })),
Preview = new ThumbnailCard { Title = text }.ToAttachment()
}
]
}
};
}
}
Befehl "Suche konfigurieren"
Das App-Manifest ist eine JSON-Datei, die die Metadaten und die Konfiguration der App definiert. Es definiert die Funktionen, die die App bereitstellt, z. B. Nachrichtenerweiterungen. Das App-Manifest ist im App-Paket enthalten. Das App-Paket ist eine ZIP-Datei, die Sie in Microsoft Teams hochladen, um die App zu installieren.
Der folgende Codeausschnitt zeigt, wie ein Suchbefehl im App-Manifest definiert wird:
"composeExtensions": [
{
"botId": "4cc3ac43-d581-403d-8bbf-ff9c0fbf3fb2",
"commands": [
{
"id": "Search",
"type": "query",
"title": "Products",
"description": "Find products by name",
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
"parameters": [
{
"name": "ProductName",
"title": "Product name",
"description": "The name of the product as a keyword",
"inputType": "text"
}
]
}
]
}
]
Ein Befehl kann einen oder mehrere Parameter enthalten. Ein Parameter ist ein Feld, das auf der Benutzeroberfläche angezeigt wird. In diesem Beispiel verfügt der Befehl über einen einzelnen Parameter namens ProductName. Der Parameter ist ein Textfeld, das der Benutzer mit dem Namen des Produkts ausfüllt, nach dem er sucht.
Microsoft Teams-Toolkit-Erweiterung für Visual Studio
Teams Toolkit für Visual Studio ist eine Erweiterung, die Tools zum Erstellen, Debuggen und Bereitstellen von Microsoft Teams-Apps bereitstellt. Teams Toolkit ist in Visual Studio integriert, um den Entwicklungsprozess zu optimieren und eine nahtlose Erfahrung für die Erstellung von Microsoft Teams-Apps bereitzustellen.
Teams Toolkit erstellt ein Gerüst für eine Projektmappe, die zwei Projekte enthält: ein Webdienstprojekt und ein Teams-App-Projekt. Das Webdienstprojekt enthält den Nachrichtenerweiterungscode, und das App-Projekt enthält das App-Manifest und andere Ressourcen, die zum Ausführen der App in Microsoft Teams erforderlich sind.
Teams Toolkit ist in das Feature Dev Tunnels in Visual Studio integriert, um die Kommunikation zwischen dem Botdienst und dem lokal ausgeführten Webdienst zu ermöglichen. Entwicklungstunnel machen den Webdienst über Ihren Computer hinaus verfügbar, damit der Botdienst ihn erreichen kann.
