Creare un'estensione del messaggio
In questa unità si apprenderà come creare un'estensione del messaggio. Si apprenderà anche come eseguire ed eseguire il debug dell'estensione del messaggio in Microsoft Teams usando Teams Toolkit.
Per creare un'estensione del messaggio, sono necessari i componenti seguenti:
- Risorsa di Azure Bot per registrare il servizio Web come bot con Bot Framework
- Servizio Web per gestire le interazioni degli utenti con l'estensione del messaggio
- Manifesto dell'app per definire le funzionalità di estensione del messaggio in Microsoft Teams
Configurare la risorsa di Azure Bot
La risorsa Azure Bot viene usata per registrare il servizio Web come bot con Bot Framework. Per creare una risorsa di Azure Bot è necessaria una registrazione Microsoft Entra dell'app. La registrazione dell'app offre un modo sicuro per autenticare e autorizzare il bot. Il servizio Web usa le credenziali di registrazione dell'app Microsoft Entra per l'autenticazione con il servizio bot.
Il frammento di codice seguente illustra come creare una risorsa di Azure Bot usando Bicep:
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
}
}
La proprietà endpoint specifica l'endpoint di messaggistica esposto nel servizio Web usato dal servizio bot per inviare richieste quando un utente interagisce con l'estensione del messaggio. La proprietà msaAppId specifica l'ID di registrazione dell'app Microsoft Entra usato per autenticare il servizio bot con il servizio Web.
I canali vengono usati per connettere il servizio bot con piattaforme di messaggistica come Microsoft Teams, Slack, Facebook Messenger e altro ancora.
Il frammento di codice seguente illustra come configurare i canali di Microsoft Teams e Microsoft 365 (Outlook e Microsoft 365 Copilot) nella risorsa di Azure Bot:
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'
}
}
Configurare il servizio Web
Il servizio Web è un'app Web che contiene il codice di estensione del messaggio. Il servizio Web è responsabile della gestione delle interazioni degli utenti con l'estensione del messaggio e usa Bot Framework SDK per comunicare con il servizio bot.
Per gestire le interazioni dell'utente, implementare:
- Endpoint di messaggistica
- Un adattatore bot
- Gestore attività bot
L'endpoint di messaggistica viene usato per ricevere richieste dal servizio bot. L'endpoint di messaggistica viene esposto nel servizio Web e passa le richieste all'adapter bot per l'elaborazione.
Il frammento di codice seguente illustra come configurare l'endpoint di messaggistica:
[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);
}
}
L'adapter bot viene usato per connettere il servizio bot al servizio Web. L'adapter bot è responsabile dell'elaborazione delle richieste in ingresso dal servizio bot e della chiamata del gestore dell'attività del bot. Il servizio Web esegue l'autenticazione con il servizio bot usando le credenziali di registrazione dell'app Microsoft Entra usate per registrare la risorsa di Azure Bot con Bot Framework.
Il frammento di codice seguente illustra come configurare l'adapter Bot nel servizio Web:
// 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>();
Per elaborare la query di ricerca utente e restituire i risultati della ricerca, implementare un gestore attività bot che eredita dalla classe TeamsActivityHandler fornita da Bot Framework SDK ed eseguire l'override del metodo OnTeamsMessagingExtensionQueryAsync .
Il frammento di codice seguente illustra come configurare il gestore attività bot nel servizio Web:
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()
}
]
}
};
}
}
Configurare il comando di ricerca
Il manifesto dell'app è un file JSON che definisce i metadati e la configurazione dell'app. Definisce le funzionalità fornite dall'app, ad esempio le estensioni dei messaggi. Il manifesto dell'app è incluso nel pacchetto dell'app. Il pacchetto dell'app è un file ZIP caricato in Microsoft Teams per installare l'app.
Il frammento di codice seguente mostra come viene definito un comando di ricerca nel manifesto dell'app:
"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"
}
]
}
]
}
]
Un comando può contenere uno o più parametri. Un parametro è un campo visualizzato nell'interfaccia utente. In questo esempio il comando ha un singolo parametro denominato ProductName. Il parametro è un campo di testo che l'utente inserisce con il nome del prodotto che sta cercando.
Teams Toolkit per Visual Studio
Teams Toolkit per Visual Studio è un'estensione che fornisce strumenti per creare, eseguire il debug e distribuire app di Microsoft Teams. Teams Toolkit si integra con Visual Studio per semplificare il processo di sviluppo e offrire un'esperienza semplice per la creazione di app di Microsoft Teams.
Teams Toolkit esegue lo scaffolding di una soluzione contenente due progetti, un progetto di servizio Web e un progetto di app teams. Il progetto di servizio Web contiene il codice di estensione del messaggio e il progetto di app contiene il manifesto dell'app e altre risorse necessarie per eseguire l'app in Microsoft Teams.
Teams Toolkit si integra con la funzionalità Tunnel di sviluppo in Visual Studio per abilitare la comunicazione tra il servizio bot e il servizio Web in esecuzione in locale. I tunnel di sviluppo espongono il servizio Web oltre il computer per consentire al servizio bot di raggiungerlo.
