Eseguire il debug di un bot con il middleware di ispezione

SI APPLICA A: SDK v4

Questo articolo descrive come eseguire il debug di un bot usando il middleware di ispezione. Questa funzionalità consente a Bot Framework Emulator di eseguire il debug del traffico all'interno e all'esterno del bot e di visualizzare lo stato corrente del bot. È possibile usare un messaggio di traccia per inviare dati all'emulatore e quindi esaminare lo stato del bot in un determinato turno della conversazione.

Si usa un EchoBot compilato in locale usando Bot Framework v4 nella guida introduttiva Creare un bot per illustrare come eseguire il debug e controllare lo stato del messaggio del bot. È anche possibile eseguire il debug di un bot usando un IDE o Bot Framework Emulator. Tuttavia, per eseguire il debug dello stato è necessario aggiungere il middleware di ispezione al bot. Gli esempi di bot di ispezione sono disponibili per C#, JavaScript, Java e Python.

Nota

Gli SDK JavaScript, C# e Python di Bot Framework continueranno a essere supportati, ma Java SDK verrà ritirato con il supporto finale a lungo termine che termina a novembre 2023.

I bot esistenti creati con Java SDK continueranno a funzionare.

Per la creazione di nuovi bot, è consigliabile usare Microsoft Copilot Studio e leggere le informazioni sulla scelta della soluzione copilota appropriata.

Per altre informazioni, vedere Il futuro della compilazione di bot.

Prerequisiti

• Conoscenza del middleware del bot e gestione dello stato
• Conoscenza di come eseguire il debug di un bot SDK-first e testare ed eseguire il debug con l'emulatore
• Installazione di Bot Framework Emulator
• Un'installazione di Dev Tunnel (se si vuole eseguire il debug di un bot configurato in Azure per l'uso di altri canali)
• Copia dell'esempio di bot di ispezione per C#, JavaScript, Java o Python

Aggiornare l'emulatore alla versione più recente

Prima di usare il middleware di ispezione dei bot per eseguire il debug del bot, aggiornare l'emulatore alla versione 4.15 o successiva. Cercare gli aggiornamenti della versione più recente.

Per controllare la versione dell'emulatore, selezionare Guida e quindi Informazioni nel menu. Verrà visualizzata la versione corrente dell'emulatore.

Aggiornare il codice del bot

C#

Il middleware dello stato di ispezione e di ispezione viene configurato nel file Startup.cs e quindi usato dall'adattatore.

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

Aggiornare la classe del bot nel file EchoBot.cs.

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

Prima di aggiornare il codice del bot, aggiornare i pacchetti alle versioni più recenti eseguendo il comando seguente nel terminale:

npm install --save botbuilder@latest

Quindi è necessario aggiornare il codice del bot JavaScript come indicato di seguito. Per altre informazioni, vedere Aggiornare il codice del bot o fare riferimento all'esempio di middleware di ispezione in GitHub.

index.js

Configurare lo stato di ispezione e aggiungere il middleware di ispezione all'adapter nel file index.js.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

Aggiornare la classe del bot nel file bot.js.

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

Configurare lo stato di ispezione e aggiungere il middleware di ispezione all'adattatore nel file di Application.java . Lo stato di ispezione viene impostato specificando una nuova spring @Bean per fornire botFrameworkHttpAdapter impostato su in @Primary modo da eseguire l'override del BotFrameworkHttpAdapter predefinito fornito dalla classe di base BotDependencyConfiguration. Vedere l'aggiornamento del codice seguente o fare riferimento all'esempio di middleware di ispezione in GitHub.

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection viene implementato come parte del pacchetto com.microsoft.bot.integration e può essere esaminato dal codice sorgente di Java SDK.

Aggiornare la classe bot nel file EchoBot.java .

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Prima di aggiornare il codice del bot, installare i pacchetti PyPI necessari eseguendo i comandi seguenti in un terminale:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Configurare lo stato di ispezione nel file app.py aggiungendo un middleware all'adapter.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

Aggiornare la classe del bot nel file echo_bot.py.

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

Eseguire test del bot in locale

Dopo aver aggiornato il codice, è possibile eseguire il bot in locale e testare la funzionalità di debug usando due emulatori: uno per inviare e ricevere messaggi e l'altro per controllare lo stato dei messaggi in modalità di debug. Per testare il bot in locale:

1. Passare alla directory del bot in un terminale ed eseguire il comando seguente per eseguire il bot in locale:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. Aprire l'emulatore. Selezionare Apri bot. Compilare l'URL del bot con http://localhost:3978/api/messages i valori MicrosoftAppId e MicrosoftAppPassword. Se si ha un bot JavaScript, è possibile trovare questi valori nel file con estensione env del bot. Se si ha un bot C#, è possibile trovare questi valori nel file appsettings.json . Per un bot Java è possibile trovare questi valori nel file application.properties . Selezionare Connetti.

3. Aprire ora un'altra finestra dell'emulatore. Questa seconda finestra dell'emulatore funzionerà come debugger. Seguire le istruzioni descritte nel passaggio precedente. Selezionare Apri in modalità di debug e quindi selezionare Connetti.

4. A questo punto verrà visualizzato un comando con un identificatore univoco (/INSPECT attach <identifier>) nell'emulatore di debug. Copiare l'intero comando con l'identificatore dall'emulatore di debug e incollarlo nella casella della chat del primo emulatore.

   Nota

   Un identificatore univoco viene generato ogni volta che l'emulatore viene avviato in modalità di debug dopo aver aggiunto il middleware di ispezione nel codice del bot.

5. È ora possibile inviare messaggi nella casella di chat del primo emulatore ed esaminare i messaggi nell'emulatore di debug. Per esaminare lo stato dei messaggi, selezionare Bot State (Stato bot) nell'emulatore di debug e espandere i valori nella finestra JSON destra. Lo stato del bot verrà visualizzato nell'emulatore di debug:

   

Ispezionare lo stato di un bot configurato in Azure

Se si vuole esaminare lo stato del bot configurato in Azure e connesso ai canali (ad esempio Teams), è necessario installare ed eseguire Dev Tunnels.

Eseguire devtunnel

A questo punto, l'emulatore è stato aggiornato alla versione più recente e aggiunto il middleware di ispezione nel codice del bot. Il passaggio successivo consiste nell'eseguire devtunnel e configurare il bot locale. Prima di eseguire devtunnel, è necessario eseguire il bot in locale.

Per eseguire il bot in locale:

1. Passare alla cartella del bot in un terminale e impostare la registrazione npm per usare le build più recenti

2. Eseguire il bot in locale. Si noterà che il bot espone un numero di porta come 3978.

3. Aprire un altro prompt dei comandi e passare alla cartella del progetto del bot. Esegui questo comando:

   devtunnel host -a -p 3978
   

4. Devtunnel è ora connesso al bot in esecuzione in locale. Copiare l'URL pubblico sicuro (HTTPS).

   

Aggiornare la risorsa bot

Ora che il bot locale è connesso a devtunnel, è possibile configurare la risorsa bot in Azure per usare l'URL devtunnel.

1. Passare alla risorsa bot in Azure. Nel menu a sinistra, in Impostazioni, selezionare Configurazione.

   1. Impostare l'endpoint di messaggistica sull'indirizzo URL devtunnel copiato. Se necessario, aggiungere /api/messages dopo l'indirizzo IP. Ad esempio: https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Selezionare Abilita endpoint di streaming.

      

   3. Selezionare Applica per salvare le modifiche.

      Suggerimento

      Se Applica non è abilitato, è possibile deselezionare Abilita endpoint di streaming e selezionare Applica, quindi selezionare Abilita endpoint di streaming e selezionare di nuovo Applica . È necessario assicurarsi che l'opzione Enable Streaming Endpoint (Abilita endpoint streaming) sia selezionata e che la configurazione dell'endpoint sia stata salvata.

2. Passare al gruppo di risorse del bot.

   1. Selezionare Distribuzione e quindi selezionare la risorsa bot che in precedenza è stata distribuita correttamente. Selezionare Modello dal menu a sinistra per ottenere MicrosoftAppId e MicrosoftAppPassword per l'app Web associata al bot.

      

   2. Aggiornare il file di configurazione del bot (appsettings.json per C# o .env per JavaScript) con MicrosoftAppId e MicrosoftAppPassword.

3. Avviare l'emulatore, selezionare Apri bot e immettere http://localhost:3978/api/messages l'URL del bot. Compilare l'ID app Microsoft e la password dell'app Microsoft con lo stesso MicrosoftAppId e MicrosoftAppPassword aggiunti al file di configurazione del bot. Selezionare Connetti.

4. Il bot in esecuzione è ora connesso alla risorsa bot in Azure. Per testare il bot in Azure in chat Web, passare alle risorse del bot, selezionare Test in chat Web e inviare messaggi al bot.

Abilitare la modalità di debug

1. Nell'emulatore selezionare Debug, quindi Avvia debug.

2. Immettere l'URL devtunnel (non dimenticare di aggiungere /api/messages) per l'URL del bot (ad esempio, https://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Per ID app Microsoft immettere l'ID app del bot.
   2. Per Password dell'app Microsoft immettere il segreto dell'app del bot.
   3. Verificare che sia selezionata anche l'opzione Open in debug mode (Apri in modalità di debug).
   4. Selezionare Connetti.

3. Con la modalità di debug abilitata, l'emulatore genera un UUID. Un UUID è un ID univoco generato ogni volta che si avvia la modalità di debug nell'emulatore.

4. Copiare e incollare l'UUID nella casella di chat test in chat Web per la chat del canale. Nella casella di chat verrà visualizzato il messaggio "Collegato alla sessione, tutto il traffico viene replicato per l'ispezione".

È possibile avviare il debug del bot inviando messaggi nella casella di chat del canale configurato. L'emulatore locale aggiornerà automaticamente i messaggi con tutti i dettagli per il debug. Per esaminare lo stato dei messaggi del bot, selezionare Bot State (Stato bot) e espandere i valori nella finestra JSON destra.

Passaggi successivi

• Informazioni su come eseguire il debug del bot usando i file di trascrizione.
• Informazioni su come eseguire il debug di una competenza o di un consumer di competenze.