Fouten opsporen in een bot met inspectie-middleware

VAN TOEPASSING OP: SDK v4

In dit artikel wordt beschreven hoe u fouten kunt opsporen in een bot met behulp van inspectie-middleware. Met deze functie kan de Bot Framework Emulator fouten opsporen in verkeer naar en uit de bot en de huidige status van de bot bekijken. U kunt een traceringsbericht gebruiken om gegevens naar de emulator te verzenden en vervolgens de status van uw bot te inspecteren op een gegeven beurt van het gesprek.

We gebruiken een EchoBot die lokaal is gebouwd met bot framework v4 in de quickstart Een bot maken om te laten zien hoe u fouten kunt opsporen en de status van de bot kunt inspecteren. U kunt ook fouten opsporen in een bot met behulp van IDE of Fouten opsporen met de Bot Framework Emulator, maar als u de foutopsporingsstatus wilt oplossen, moet u inspectie-middleware toevoegen aan uw bot. De voorbeelden van de inspectiebot zijn beschikbaar voor C#, JavaScript, Java en Python.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Vereisten

• Kennis van bot Middleware en beheerstatus
• Kennis van het opsporen van fouten in een SDK-eerste bot en testen en fouten opsporen met de emulator
• Een installatie van de Bot Framework Emulator
• Een installatie van Dev Tunnel (als u fouten wilt opsporen in een bot die is geconfigureerd in Azure om andere kanalen te gebruiken)
• Een kopie van het voorbeeld van de inspectiebot voor C#, JavaScript, Java of Python

Uw emulator bijwerken naar de nieuwste versie

Voordat u botinspectie-middleware gebruikt om fouten in uw bot op te sporen, moet u de emulator bijwerken naar versie 4.15 of hoger. Controleer de nieuwste versie op updates.

Als u de versie van uw emulator wilt controleren, selecteert u Help en vervolgens Over in het menu. U ziet de huidige versie van uw emulator.

Uw botcode bijwerken

C#

De inspectiestatus en inspectie-middleware worden geconfigureerd in het Startup.cs-bestand en vervolgens gebruikt door de adapter.

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");
            };
        }

Werk de botklasse bij in het EchoBot.cs-bestand .

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

Voordat u de code van uw bot bijwerkt, moet u de pakketten bijwerken naar de nieuwste versies door de volgende opdracht uit te voeren in uw terminal:

npm install --save botbuilder@latest

Vervolgens moet u de code van uw JavaScript-bot als volgt bijwerken. Meer informatie vindt u hier: Werk de code van uw bot bij of raadpleeg het voorbeeld van de inspectie-middleware op GitHub.

index.js

Stel de inspectiestatus in en voeg de inspectie-middleware toe aan de adapter in het index.js bestand.

// 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

Werk de botklasse bij in het bot.js-bestand .

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

Stel de inspectiestatus in en voeg de inspectie-middleware toe aan de adapter in het bestand Application.java . De inspectiestatus wordt ingesteld door een nieuwe Spring @Bean te leveren voor het leveren van de BotFrameworkHttpAdapter die is ingesteld op, @Primary zodat de standaard BotFrameworkHttpAdapter wordt overschreven die wordt geleverd door de BotDependencyConfiguration-basisklasse. Zie de onderstaande code-update of raadpleeg het voorbeeld van de inspectie-middleware op 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 wordt geïmplementeerd als onderdeel van het com.microsoft.bot.integration-pakket en kan worden gecontroleerd vanuit de Java SDK-broncode.

Werk de botklasse bij in het EchoBot.java-bestand .

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

Voordat u de code van uw bot bijwerkt, installeert u de benodigde PyPI-pakketten door de volgende opdrachten uit te voeren in een terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Stel de inspectiestatus in het app.py bestand in door een middleware toe te voegen aan de 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)

Werk de botklasse bij in het echo_bot.py-bestand .

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

Uw bot lokaal testen

Nadat u de code hebt bijgewerkt, kunt u uw bot lokaal uitvoeren en de foutopsporingsfunctie testen met behulp van twee emulators: één om berichten te verzenden en te ontvangen, en de andere om de status van berichten in de foutopsporingsmodus te controleren. Uw bot lokaal testen:

1. Ga naar de map van uw bot in een terminal en voer de volgende opdracht uit om uw bot lokaal uit te voeren:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Open uw emulator. Selecteer Bot openen. Vul de BOT-URL in met http://localhost:3978/api/messages de waarden MicrosoftAppId en MicrosoftAppPassword . Als u een JavaScript-bot hebt, kunt u deze waarden vinden in het .env-bestand van uw bot. Als u een C#-bot hebt, kunt u deze waarden vinden in het bestand appsettings.json . Voor een Java-bot vindt u deze waarden in het bestand application.properties . Selecteer Verbinding maken.

3. Open nu een ander emulatorvenster. Dit tweede emulatorvenster werkt als een foutopsporingsprogramma. Volg de instructies zoals beschreven in de vorige stap. Schakel Open in de foutopsporingsmodus in en selecteer Vervolgens Verbinding maken.

4. Op dit moment ziet u een opdracht met een unieke id (/INSPECT attach <identifier>) in uw foutopsporingsemulator. Kopieer de hele opdracht met de id uit de foutopsporingsemulator en plak deze in het chatvak van de eerste emulator.

   Notitie

   Er wordt een unieke id gegenereerd wanneer de emulator wordt gestart in de foutopsporingsmodus nadat u de inspectie-middleware in de code van uw bot hebt toegevoegd.

5. U kunt nu berichten verzenden in het chatvak van uw eerste emulator en de berichten controleren in de foutopsporingsemulator. Als u de status van de berichten wilt controleren, selecteert u BotStatus in de foutopsporingsemulator en ontvouwt u waarden in het rechter JSON-venster . U ziet de status van uw bot in de foutopsporingsemulator:

   

De status controleren van een bot die is geconfigureerd in Azure

Als u de status van uw bot wilt inspecteren die is geconfigureerd in Azure en verbonden met kanalen (zoals Teams), moet u Dev Tunnels installeren en uitvoeren.

Devtunnel uitvoeren

Op dit moment hebt u uw emulator bijgewerkt naar de nieuwste versie en de inspectie-middleware toegevoegd aan de code van uw bot. De volgende stap is het uitvoeren van devtunnel en het configureren van uw lokale bot. Voordat u devtunnel uitvoert, moet u uw bot lokaal uitvoeren.

Uw bot lokaal uitvoeren:

1. Ga naar de map van uw bot in een terminal en stel uw NPM-registratie in om de meest recente builds te gebruiken

2. Voer uw bot lokaal uit. U ziet dat uw bot een poortnummer beschikbaar maakt, zoals 3978.

3. Open een andere opdrachtprompt en ga naar de projectmap van uw bot. Voer de volgende opdracht uit:

   devtunnel host -a -p 3978
   

4. devtunnel is nu verbonden met uw lokaal actieve bot. Kopieer de openbare URL van secure (HTTPS).

   

Uw botresource bijwerken

Nu uw lokale bot is verbonden met devtunnel, kunt u uw botresource in Azure configureren om de devtunnel-URL te gebruiken.

1. Ga naar uw botresource in Azure. Selecteer Configuratie in het linkermenu onder Instellingen.

   1. Stel het berichteindpunt in op het url-adres van devtunnel dat u hebt gekopieerd. Voeg indien nodig /api/messages toe na het IP-adres. Bijvoorbeeld: https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Selecteer Streaming-eindpunt inschakelen.

      

   3. Selecteer Toepassen om uw wijzigingen op te slaan.

      Tip

      Als Apply niet is ingeschakeld, kunt u het selectievakje Streaming-eindpunt inschakelen uitschakelen en Toepassen selecteren. Schakel vervolgens Streaming-eindpunt inschakelen in en selecteer Opnieuw toepassen. U moet ervoor zorgen dat streaming-eindpunt inschakelen is ingeschakeld en dat de configuratie van het eindpunt wordt opgeslagen.

2. Ga naar de resourcegroep van uw bot.

   1. Selecteer Implementatie en selecteer vervolgens de botresource die eerder is geïmplementeerd. Selecteer Sjabloon in het linkermenu om de MicrosoftAppId en MicrosoftAppPassword op te halen voor de web-app die is gekoppeld aan uw bot.

      

   2. Werk het configuratiebestand van uw bot (appsettings.json voor C# of .env voor JavaScript) bij met de MicrosoftAppId en MicrosoftAppPassword.

3. Start uw emulator, selecteer Bot openen en voer http://localhost:3978/api/messages de BOT-URL in. Vul microsoft-app-id en Microsoft App-wachtwoord in met dezelfde MicrosoftAppId en MicrosoftAppPassword die u hebt toegevoegd aan het configuratiebestand van onze bot. Selecteer vervolgens Connect.

4. Uw actieve bot is nu verbonden met uw botresource in Azure. Als u uw bot in Azure in Webchat wilt testen, gaat u naar uw botbronnen, selecteert u Testen in Webchat en verzendt u berichten naar uw bot.

Foutopsporingsmodus inschakelen

1. Selecteer Fouten opsporen in uw emulator en start vervolgens Foutopsporing.

2. Voer de devtunnel-URL in (vergeet niet om /api/messages toe te voegen) voor de Bot-URL (bijvoorbeeldhttps://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Voer voor Microsoft App ID de app-id van uw bot in.
   2. Voer voor het wachtwoord van de Microsoft-app het app-geheim van uw bot in.
   3. Zorg ervoor dat Openen in de foutopsporingsmodus ook is ingeschakeld.
   4. Selecteer Verbinding maken.

3. Als de foutopsporingsmodus is ingeschakeld, genereert de emulator een UUID. Een UUID is een unieke id die wordt gegenereerd telkens wanneer u de foutopsporingsmodus in uw emulator start.

4. Kopieer en plak de UUID in de test in Webchat chatvak voor het chatvak van uw kanaal. U ziet het bericht 'Gekoppeld aan sessie, al het verkeer wordt gerepliceerd voor inspectie' in het chatvak.

U kunt beginnen met het opsporen van fouten in uw bot door berichten te verzenden in het chatvak van het geconfigureerde kanaal. De lokale emulator werkt de berichten automatisch bij met alle details voor foutopsporing. Als u de status van uw bot van berichten wilt controleren, selecteert u BotStatus en vouwt u de waarden uit in het rechter JSON-venster.

Volgende stappen

• Meer informatie over het opsporen van fouten in uw bot met behulp van transcriptbestanden.
• Meer informatie over het opsporen van fouten in een vaardigheid of vaardigheidsgebruiker.