Indice dei contenuti
Questo articolo fa parte di una serie di approfondimenti sul Microsoft Bot Framework, il sistema messo a disposizione da Microsoft per sviluppare bot di vario tipo, ed è dedicato all'analisi del codice sorgente di uno dei tre tremplate forniti dal Microsoft Bot Framework SDK per Visual Studio 2019. Questa code review ci darà l'occasione di approfondire ulteriormente i concetti chiave dell’SDK relativi al funzionamento dell’architettura e delle interfacce di comunicazione di cui già abbiamo parlato nel corso dell'articolo precedente.
Visual Studio AI Bots Templates
Una volta installato l'ambiente di sviluppo (come spiegato qui) potremo lanciare Visual Studio 2019 e selezionare la creazione di un nuovo progetto. I template che ci interessa prendere in considerazione sono quelli che appartengono all’insieme AI Bots, selezionabili tramite la casella dropdown in alto a destra: poiché abbiamo intenzione di programmare il nostro bot in C# e in ambiente Windows, è bene selezionare anche il linguaggio di programmazione e il sistema operativo tramite le altre due dropdown.
I template a disposizione sono riconducibili a tre tipologie principali:
- Empty Bot. Il classico boilerplate, ovvero un’applicazione contenente un bot privo di funzionalità: ideale per gli utenti esperti o per sperimentare esempi di codice già pronti.
- Echo Bot. Un bot che elabora i messaggi dell’utente e li ripete: ideale per muovere i primi passi all’interno del Bot Framework.
- Core Bot. Un bot completo, che include una serie di funzionalità principali comuni alla maggior parte dei bot. Ideale per gli utenti che vogliono sviluppare un bot conversazionale che utilizza il Language Understanding (LUIS), il servizio di intelligenza artificiale di Microsoft che consente agli utenti di interagire con le applicazioni, i bot e i dispositivi IoT usando il linguaggio naturale.
Prima di addentrarci all’interno delle funzionalità più avanzate, diamo un’occhiata al modello più semplice, ovvero l’Echo Bot. Selezioniamo dunque questo template, avendo cura di scegliere l’ultima versione del framework .NET Core: ad oggi la 3.1, anche se tra meno di un mese dovremmo avere a disposizione la 5.
Il progetto consiste in una web application che prevede i seguenti elementi chiave:
- una pagina HTML statica (/wwwroot/default.html), che ha il solo scopo di visualizzare a schermo le istruzioni per effettuare il testing del bot.
- un controller (/Controllers/BotController.cs), che ha il compito di ricevere le richieste HTTP e passarle a un adapter che, a sua volta, gestisce le interazioni tra le richieste HTTP e il bot, restituendo la risposta corrispondente.
- La classe relativa al bot (/Bots/EchoBot.cs), una classe C# che contiene le logiche di funzionamento. Come si può vedere dal codice EchoBot è una sottoclasse di ActivityHandler, una classe messa a disposizione dalla SDK che consente di gestire una serie di eventi ricevuti tramite una serie di richieste HTTP POST asincrone.
Echo Bot: test funzionale
Prima di dare un'occhiata al codice, proviamo ad effettuare il test di questo Echo Bot con il Bot Framework Emulator: anzitutto lanciamo l’applicazione da Visual Studio, così da ricevere il relativo set di istruzioni all’interno del nostro browser predefinito: lanciamo quindi il Bot Framework Emulator, avendo cura di fornire alla app i permessi di accesso alla nostra rete privata al momento dell'installazione.
Una volta lanciato, facciamo click sul pulsante Open Bot e inseriamo la URL locale mostrata all’interno della pagina di istruzioni. Facciamo quindi click su Connect per accedere a una nuova tab, denominata Live Chat, attraverso la quale potremo interagire con il bot.
Come si può vedere dal video, il bot restituirà qualsiasi frase che andremo a digitare.
Uno sguardo al codice
Diamo un’occhiata al codice sorgente di Echo Bot per vedere in che modo è stato implementato questo comportamento, cominciando con la classe EchoBot.cs.
Come si può notare, la quasi totalità del lavoro si svolge all’interno del metodo OnMessageActivityAsync, un handler che viene eseguito ogni volta che un utente che si trova nella chat in cui è presente il bot scrive un messaggio rivolto al bot.
|
1 2 3 4 5 |
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken) { var replyText = $"Echo: {turnContext.Activity.Text}"; await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken); } |
A seguito di questo evento, il codice recupera il messaggio digitato dall’utente in questione e lo ripete, inviando a sua volta una MessageActivity contenente la “risposta”, chiamiamola così, del bot.
Cosa significa “messaggio rivolto al bot”? In una chat 1:1 parliamo di qualsiasi messaggio, in quanto il framework lo considera automaticamente rivolto al bot; in una chat di gruppo, parliamo di qualsiasi messaggio che contenga una mention al bot: in altre parole, l’utente che vuole interagire col bot in una chat di gruppo o in un canale MS Teams deve necessariamente menzionare il bot all’interno del messaggio. Ora, poiché le mentions fanno parte del testo del messaggio, questo causerebbe un problema al nostro Echo Bot, in quanto il messaggio dell’utente in questione verrebbe ripetuto con tanto di mention al suo interno: per evitare questo effetto, dovremmo quindi andare a eliminare la mention dal nostro testo di risposta con uno string.Replace o metodo similare.
Diamo ora un’occhiata al secondo metodo presente all’interno della classe Echo Bot:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
protected override async Task OnMembersAddedAsync( IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken) { var welcomeText = "Hello and welcome!"; foreach (var member in membersAdded) { if (member.Id != turnContext.Activity.Recipient.Id) { await turnContext.SendActivityAsync( MessageFactory.Text(welcomeText, welcomeText), cancellationToken); } } } |
anche in questo caso possiamo vedere che si tratta di un handler, che in questo caso risponde a un evento azionato da un cambio delle caratteristiche della conversazione: nello specifico, l’evento gestisce l’ingresso di uno o più nuovi utenti nella chat. L’implementazione non fa altro che passare in rassegna l’elenco dei nuovi membri che hanno effettuato l’ingresso, contenuti in una lista ricevuta dal metodo come primo parametro, e rispondere a ciascuno di essi con un messaggio di benvenuto.
Ovviamente, poiché l’evento scatta anche quando è il bot stesso a entrare nella chat, l’handler ha la necessità di controllare che l’ID del nuovo membro non sia il medesimo dell’ID dell’utente che ha ricevuto la notifica relativa a questo evento, che nel nostro caso è ovviamente il bot.
Se provassimo a commentare l’istruzione IF che determina questa esclusione e a ripetere il test con il Bot Framework Emulator, il bot restituirebbe due messaggi di benvenuto: uno a se stesso, e uno a noi.
Questo comportamento andrebbe a verificarsi perché la chat viene creata dall’emulatore nell’istante in cui noi effettuiamo l’ingresso; di conseguenza, la lista dei nuovi membri ricevuta dal bot conterrà sia il nostro utente di test che il bot medesimo.
Conclusioni
Per il momento è tutto. Nel prossimo articolo ci dedicheremo all'analisi del codice di un bot leggermente più complesso che ci consentirà di approfondire ulteriori aspetti della Bot Framework SDK, tra cui il concetto di Dialog e i tre stati che il framework mette a disposizione per memorizzare le informazioni relative alla chat, agli utenti e al rapporto tra questi due elementi fondamentali: ConversationState, UserState e PrivateConversationState.
Articoli correlati
- Indice degli argomenti
- Introduzione: cos'è un bot?
- Microsoft Bot Framework: concetti generali
- Microsoft Bot Framework: Esempio semplice - Echo Bot
- Microsoft Bot Framework: Esempio complesso - Dialog Bot
- Microsoft Bot Framework: Deploy su Azure Bot Service
- Microsoft Bot Framework: Integrazione con MS Teams
