Felsöka en robot med kontrollmellanprogram

GÄLLER FÖR: SDK v4

Den här artikeln beskriver hur du felsöker en robot med hjälp av kontrollmellanprogram. Med den här funktionen kan Bot Framework-emulatorn felsöka trafik till och från roboten och se robotens aktuella tillstånd. Du kan använda ett spårningsmeddelande för att skicka data till emulatorn och sedan inspektera robotens tillstånd i en viss konversation.

Vi använder en EchoBot som skapats lokalt med hjälp av Bot Framework v4 i snabbstarten Skapa en robot för att visa hur du felsöker och inspekterar robotens meddelandetillstånd. Du kan också felsöka en robot med hjälp av IDE eller Felsöka med Bot Framework-emulatorn, men för att felsöka tillstånd måste du lägga till kontrollmellanprogram i roboten. Exempel på inspektionsrobotar är tillgängliga för C#, JavaScript, Java och Python.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot kan du använda Microsoft Copilot Studio och läsa om hur du väljer rätt copilot-lösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

• Kunskap om robotmellanprogram och hantera tillstånd
• Kunskap om hur du felsöker en SDK-första robot och testa och felsöka med emulatorn
• En installation av Bot Framework-emulatorn
• En installera ngrok (om du vill felsöka en robot som konfigurerats i Azure för att använda andra kanaler)
• En kopia av kontrollrobotexemplet för C#, JavaScript, Java eller Python

Uppdatera emulatorn till den senaste versionen

Innan du använder mellanprogrammet för robotgranskning för att felsöka roboten uppdaterar du emulatorn till version 4.5 eller senare. Kontrollera den senaste versionen för uppdateringar.

Om du vill kontrollera versionen av emulatorn väljer du Hjälp och sedan Om på menyn. Du ser den aktuella versionen av emulatorn.

Uppdatera robotkoden

C#

Kontrolltillståndet och kontrollmellanprogrammet konfigureras i filen Startup.cs och används sedan av adaptern.

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

Uppdatera robotklassen i filen 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

Innan du uppdaterar robotens kod uppdaterar du dess paket till de senaste versionerna genom att köra följande kommando i terminalen:

npm install --save botbuilder@latest

Sedan måste du uppdatera koden för din JavaScript-robot på följande sätt. Du kan läsa mer här: Uppdatera robotens kod eller se exempel på mellanprogram för inspektion på GitHub.

index.js

Konfigurera inspektionstillståndet och lägg till kontrollmellanprogrammet i adaptern i index.js-filen.

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

Uppdatera robotklassen i filen 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

Konfigurera kontrolltillståndet och lägg till kontrollmellanprogrammet i adaptern i Application.java-filen . Inspektionstillståndet anges genom att tillhandahålla en ny Spring @Bean för att tillhandahålla BotFrameworkHttpAdapter som är inställd @Primary på så att den åsidosätter standardbasklassen BotFrameworkHttpAdapter som tillhandahålls av basklassen BotDependencyConfiguration. Se koduppdateringen nedan eller se exempel på mellanprogram för inspektion på 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 implementeras som en del av com.microsoft.bot.integration-paketet och kan granskas från Java SDK-källkoden.

Uppdatera robotklassen i filen 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

Innan du uppdaterar robotens kod installerar du nödvändiga PyPI-paket genom att köra följande kommandon i en terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Konfigurera inspektionstillståndet i app.py-filen genom att lägga till ett mellanprogram i adaptern.

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)

Uppdatera robotklassen i filen echo_bot.py .

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

Testa roboten lokalt

När du har uppdaterat koden kan du köra roboten lokalt och testa felsökningsfunktionen med hjälp av två emulatorer: en för att skicka och ta emot meddelanden och den andra för att inspektera tillståndet för meddelanden i felsökningsläge. Så här testar du roboten lokalt:

1. Gå till robotens katalog i en terminal och kör följande kommando för att köra roboten lokalt:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Öppna emulatorn. Välj Öppna robot. Fyll i bot-URL :en med http://localhost:3978/api/messages och värdena MicrosoftAppId och MicrosoftAppPassword . Om du har en JavaScript-robot kan du hitta dessa värden i robotens .env-fil . Om du har en C#-robot kan du hitta dessa värden i filen appsettings.json . För en Java-robot hittar du dessa värden i filen application.properties . Välj Anslut.

3. Öppna nu ett nytt emulatorfönster. Det andra emulatorfönstret fungerar som ett felsökningsprogram. Följ anvisningarna enligt beskrivningen i föregående steg. Kontrollera Öppna i felsökningsläge och välj sedan Anslut.

4. Nu visas ett kommando med en unik identifierare (/INSPECT attach <identifier>) i felsökningsemulatorn. Kopiera hela kommandot med identifieraren från felsökningsemulatorn och klistra in den i chattrutan i den första emulatorn.

   Kommentar

   En unik identifierare genereras varje gång emulatorn startas i felsökningsläge när du har lagt till kontrollmellanprogrammet i robotens kod.

5. Nu kan du skicka meddelanden i chattrutan i din första emulator och inspektera meddelandena i felsökningsemulatorn. Om du vill kontrollera statusen för meddelandena väljer du Robottillstånd i felsökningsemulatorn och utvecklar värden i det högra JSON-fönstret . Du ser tillståndet för roboten i felsökningsemulatorn:

   

Kontrollera tillståndet för en robot som konfigurerats i Azure

Om du vill kontrollera tillståndet för din robot som konfigurerats i Azure och är ansluten till kanaler (till exempel Teams) måste du installera och köra ngrok.

Kör ngrok

Nu har du uppdaterat emulatorn till den senaste versionen och lagt till kontrollmellanprogrammet i robotens kod. Nästa steg är att köra ngrok och konfigurera din lokala robot. Innan du kör ngrok måste du köra roboten lokalt.

Så här kör du roboten lokalt:

1. Gå till robotens mapp i en terminal och ställ in npm-registreringen så att den använder de senaste versionerna

2. Kör roboten lokalt. Du ser din robot exponera ett portnummer som 3978.

3. Öppna en annan kommandotolk och gå till robotens projektmapp. Kör följande kommando:

   ngrok http 3978
   

4. ngrok är nu ansluten till din lokalt aktiva robot. Kopiera den säkra offentliga IP-adressen (HTTPS).

   

Uppdatera robotresursen

Nu när din lokala robot är ansluten till ngrok kan du konfigurera robotresursen i Azure så att den använder ngrok-URL:en.

1. Gå till robotresursen i Azure. Välj Konfiguration under Inställningar på den vänstra menyn.

   1. Ange meddelandeslutpunkten till den ngrok-IP-adress som du kopierade. Lägg vid behov till /api/messages efter IP-adressen. Exempel: https://e58549b6.ngrok.io/api/messages

   2. Välj Aktivera slutpunkt för direktuppspelning.

      

   3. Tryck på Apply (Verkställ) för att spara ändringarna.

      Dricks

      Om Använd inte är aktiverat kan du avmarkera Aktivera slutpunkt för direktuppspelning och välja Tillämpa. Markera sedan Aktivera slutpunkt för direktuppspelning och välj Tillämpa igen. Du måste se till att Aktivera slutpunkt för direktuppspelning är markerat och att konfigurationen av slutpunkten sparas.

2. Gå till robotens resursgrupp.

   1. Välj Distribution och välj sedan robotresursen som tidigare har distribuerats. Välj Mall på den vänstra menyn för att hämta MicrosoftAppId och MicrosoftAppPassword för webbappen som är associerad med din robot.

      

   2. Uppdatera robotens konfigurationsfil (appsettings.json för C# eller .env för JavaScript) med MicrosoftAppId och MicrosoftAppPassword.

3. Starta emulatorn, välj Öppna robot och ange http://localhost:3978/api/messages i robot-URL:en. Fyll i Microsoft App-ID och Microsoft App-lösenord med samma MicrosoftAppId och MicrosoftAppPassword som du lade till i robotens konfigurationsfil. Välj sedan Anslut.

4. Din robot som körs är nu ansluten till robotresursen i Azure. Om du vill testa din robot i Azure i webbchatt går du till dina robotresurser, väljer Testa i webbchatt och skickar meddelanden till din robot.

Aktivera felsökningsläge

1. I emulatorn väljer du Felsök och sedan Starta felsökning.

2. Ange ngrok-IP-adressen (glöm inte att lägga till /api/messages) för robot-URL :en (till exempel https://e58549b6.ngrok.io/api/messages).

   1. För Microsoft App-ID anger du robotens app-ID.
   2. Ange robotens apphemlighet för Microsoft App-lösenord.
   3. Kontrollera att Även Öppna i felsökningsläge är markerat.
   4. Välj Anslut.

3. När felsökningsläget är aktiverat genererar emulatorn ett UUID. Ett UUID är ett unikt ID som genereras varje gång du startar felsökningsläget i emulatorn.

4. Kopiera och klistra in UUID i chattrutan Testa i webbchatt för kanalens chattruta. Meddelandet "Ansluten till session, all trafik replikeras för inspektion" visas i chattrutan.

Du kan börja felsöka roboten genom att skicka meddelanden i den konfigurerade kanalens chattruta. Din lokala emulator uppdaterar automatiskt meddelandena med all information för felsökning. Om du vill kontrollera robotens status för meddelanden väljer du Robottillstånd och utvecklar värdena i rätt JSON-fönster.

Nästa steg

• Lär dig hur du felsöker din robot med hjälp av transkriptionsfiler.
• Lär dig hur du felsöker en kunskaps- eller kunskapskonsument.