Robot hibakeresése ellenőrző köztes szoftverrel

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Ez a cikk azt ismerteti, hogyan lehet hibakeresést végezni egy roboton az ellenőrző köztes szoftverrel. Ez a funkció lehetővé teszi a Bot Framework Emulator számára, hogy hibakeresést hajtson végre a robotba és azon kívül, valamint hogy lássa a robot aktuális állapotát. Nyomkövetési üzenet használatával adatokat küldhet az Emulátornak, majd megvizsgálhatja a robot állapotát a beszélgetés bármely során.

A Robot keretrendszer v4 használatával helyileg létrehozott EchoBotot használunk a Robot létrehozása rövid útmutatóban , amely bemutatja a robot üzenetállapotának hibakeresését és vizsgálatát. A robotok hibakeresését ide vagy Hibakeresés funkcióval is elvégezheti a Bot Framework Emulator használatával, de a hibakereséshez ellenőrző köztes szoftvereket kell hozzáadnia a robothoz. Az ellenőrzőrobot-minták C#, JavaScript, Java és Python esetén érhetők el.

Feljegyzés

A Bot Framework JavaScript, C# és Python SDK-k továbbra is támogatottak lesznek, a Java SDK-t azonban 2023 novemberében végső hosszú távú támogatással kivonják.

A Java SDK-val létrehozott meglévő robotok továbbra is működni fognak.

Az új robotépítéshez fontolja meg a Microsoft Copilot Studio használatát, és olvassa el a megfelelő copilot-megoldás kiválasztását.

További információ: A robotépítés jövője.

Előfeltételek

• A köztes szoftver és az állapotkezelés robotjának ismerete
• Az SDK-első robot hibakeresésének, valamint az Emulator tesztelésének és hibakeresésének ismerete
• A Bot Framework Emulator telepítése
• A Dev Tunnel telepítése (ha az Azure-ban konfigurált robotot szeretne hibakeresésre más csatornák használatára)
• A vizsgálati robot mintájának másolata C#, JavaScript, Java vagy Python esetén

Az Emulator frissítése a legújabb verzióra

Mielőtt robotvizsgálati köztes szoftvereket használna a robot hibakereséséhez, frissítse az Emulátort a 4.15-ös vagy újabb verzióra. Frissítésekért tekintse meg a legújabb verziót .

Az Emulator verziójának ellenőrzéséhez válassza a Súgó, majd a Névjegy lehetőséget a menüben. Ekkor megjelenik az Emulator aktuális verziója.

A robotkód frissítése

C#

A vizsgálati állapot és a vizsgálati köztes szoftver konfigurálva van a Startup.cs fájlban, majd az adapter használja.

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

Frissítse a robotosztályt a EchoBot.cs fájlban.

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

A robot kódjának frissítése előtt frissítse a csomagjait a legújabb verziókra az alábbi parancs végrehajtásával a terminálon:

npm install --save botbuilder@latest

Ezután frissítenie kell a JavaScript-robot kódját az alábbiak szerint. További információt itt talál: Frissítse a robot kódját, vagy tekintse meg a Felügyeleti köztes szoftver mintáját a GitHubon.

index.js

Állítsa be a vizsgálati állapotot, és adja hozzá a vizsgálati köztes szoftvert az adapterhez a index.js fájlban.

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

Frissítse a robotosztályt a bot.js fájlban.

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

Állítsa be a vizsgálati állapotot, és adja hozzá a vizsgálati köztes szoftvereket az adapterhez a Application.java fájlban. A vizsgálati állapot úgy van beállítva, hogy egy új rugót @Bean biztosít a BotFrameworkHttpAdapter számára, amely úgy van beállítva @Primary , hogy felülbírálja a BotDependencyConfiguration alaposztály által biztosított alapértelmezett BotFrameworkHttpAdapter értéket. Tekintse meg az alábbi kódfrissítést, vagy tekintse meg a Felügyeleti köztes szoftver mintáját a GitHubon.

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

Az AdapterWithInspection a com.microsoft.bot.integration csomag részeként van implementálva, és a Java SDK forráskódjából tekinthető meg.

Frissítse a robotosztályt a EchoBot.java fájlban.

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

A robot kódjának frissítése előtt telepítse a szükséges PyPI-csomagokat a következő parancsok terminálon való futtatásával:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Állítsa be a vizsgálati állapotot a app.py fájlban egy köztes szoftver adapterhez való hozzáadásával.

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)

Frissítse a robotosztályt a echo_bot.py fájlban.

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

A robot helyi tesztelése

A kód frissítése után helyileg futtathatja a robotot, és tesztelheti a hibakeresési funkciót két Emulátor használatával: az egyik az üzenetek küldéséhez és fogadásához, a másik pedig az üzenetek állapotának hibakeresési módban történő vizsgálatához. A robot helyi tesztelése:

1. Nyissa meg a robot könyvtárát egy terminálban, és hajtsa végre a következő parancsot a robot helyi futtatásához:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Nyissa meg az Emulátort. Válassza a Robot megnyitása lehetőséget. Töltse ki a robot URL-címét a MicrosoftAppId és a MicrosoftAppPassword értékekkelhttp://localhost:3978/api/messages. Ha JavaScript-robottal rendelkezik, ezeket az értékeket megtalálhatja a robot .env fájljában. Ha rendelkezik C#-robottal, ezeket az értékeket a appsettings.json fájlban találja. Java-robot esetén ezeket az értékeket az application.properties fájlban találja. Válassza a Kapcsolódás lehetőséget.

3. Most nyisson meg egy másik Emulator-ablakot. Ez a második Emulator-ablak hibakeresőként fog működni. Kövesse az előző lépésben leírt utasításokat. Jelölje be a Megnyitás hibakeresési módban jelölőnégyzetet, majd válassza a Csatlakozás lehetőséget.

4. Ekkor megjelenik egy egyedi azonosítóval (/INSPECT attach <identifier>) rendelkező parancs a hibakeresési Emulátorban. Másolja ki a teljes parancsot a hibakereső Emulátor azonosítójával, és illessze be az első Emulátor csevegőablakába.

   Feljegyzés

   Minden alkalommal egyedi azonosító jön létre, amikor az Emulátor hibakeresési módban indul el, miután hozzáadta az ellenőrző köztes szoftvert a robot kódjához.

5. Most már küldhet üzeneteket az első Emulátor csevegőablakában, és megvizsgálhatja az üzeneteket a hibakereső Emulátorban. Az üzenetek állapotának vizsgálatához válassza a Robot állapota lehetőséget a hibakeresési Emulátorban, és bontsa ki az értékeket a jobb oldali JSON-ablakban. A robot állapotát a hibakeresési Emulátorban láthatja:

   

Az Azure-ban konfigurált robot állapotának vizsgálata

Ha meg szeretné vizsgálni az Azure-ban konfigurált és csatornákhoz (például Teamshez) csatlakoztatott robot állapotát, telepítenie és futtatnia kell a Fejlesztői alagutakat.

A devtunnel futtatása

Ezen a ponton frissítette az Emulatort a legújabb verzióra, és hozzáadta az ellenőrző köztes szoftvereket a robot kódjához. A következő lépés a devtunnel futtatása és a helyi robot konfigurálása. A devtunnel futtatása előtt helyileg kell futtatnia a robotot.

A robot helyi futtatása:

1. Nyissa meg a robot mappáját egy terminálban, és állítsa be az npm-regisztrációt a legújabb buildek használatára

2. Futtassa helyileg a robotot. Látni fogja, hogy a robot egy ilyen 3978portszámot tesz elérhetővé.

3. Nyisson meg egy másik parancssort, és nyissa meg a robot projektmappáját. Futtassa az alábbi parancsot:

   devtunnel host -a -p 3978
   

4. A devtunnel mostantól csatlakozik a helyileg futó robothoz. Másolja ki a biztonságos (HTTPS) nyilvános URL-címet.

   

A roboterőforrás frissítése

Most, hogy a helyi robot csatlakozott a devtunnelhez, konfigurálhatja a roboterőforrást az Azure-ban a devtunnel URL-címének használatára.

1. Nyissa meg a roboterőforrást az Azure-ban. A bal oldali menü Beállítások területén válassza a Konfiguráció lehetőséget.

   1. Állítsa az üzenetkezelési végpontot a másolt devtunnel URL-címre. Szükség esetén adjon hozzá /api/üzeneteket az IP-cím után. Például: https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Válassza a Streamvégpont engedélyezése lehetőséget.

      

   3. A módosítások mentéséhez válassza az Alkalmaz lehetőséget.

      Tipp.

      Ha az Alkalmazás nincs engedélyezve, törölje a jelet a Streamvégpont engedélyezése jelölőnégyzetből, és válassza az Alkalmaz lehetőséget, majd jelölje be a Streamvégpont engedélyezése jelölőnégyzetet, majd kattintson ismét az Alkalmaz gombra. Győződjön meg arról, hogy a streamvégpont engedélyezése be van jelölve, és a végpont konfigurációja mentésre kerül.

2. Nyissa meg a robot erőforráscsoportját.

   1. Válassza az Üzembe helyezés lehetőséget, majd válassza ki a korábban sikeresen üzembe helyezett roboterőforrást. A bal oldali menüBen válassza a Sablon lehetőséget a robothoz társított webalkalmazásHoz tartozó MicrosoftAppId és MicrosoftAppPassword beszerzéséhez.

      

   2. Frissítse a robot konfigurációs fájlját (appsettings.json a C#-hoz vagy a .env for JavaScripthez) a MicrosoftAppId és a MicrosoftAppPassword használatával.

3. Indítsa el az Emulátort, válassza a Robot megnyitása lehetőséget, és írja be http://localhost:3978/api/messages a robot URL-címét. Töltse ki a Microsoft Alkalmazásazonosítót és a Microsoft App jelszavát ugyanazzal a MicrosoftAppId és MicrosoftAppPassword azonosítóval, mint amit a robot konfigurációs fájljában hozzáadott. Ezután válassza a Csatlakozás lehetőséget.

4. A futó robot most már csatlakozik a robot erőforrásához az Azure-ban. Ha tesztelni szeretné a robotot az Azure-ban webchat, nyissa meg a robot erőforrásait, válassza a Tesztelés webchat lehetőséget, és küldjön üzeneteket a robotnak.

Hibakeresési mód engedélyezése

1. Az Emulátorban válassza a Hibakeresés lehetőséget, majd indítsa el a hibakeresést.

2. Adja meg a devtunnel URL-címét (ne felejtsen el /api/üzeneteket hozzáadni) a robot URL-címéhez (példáulhttps://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. A Microsoft Alkalmazásazonosító mezőben adja meg a robot alkalmazásazonosítóját.
   2. A Microsoft App jelszavához adja meg a robot alkalmazáskulcsát.
   3. Győződjön meg arról, hogy a Megnyitás hibakeresési módban is be van jelölve.
   4. Válassza a Kapcsolódás lehetőséget.

3. Ha engedélyezve van a hibakeresési mód, az Emulátor létrehoz egy UUID azonosítót. Az UUID egy egyedi azonosító, amely minden alkalommal létrejön, amikor elindítja a hibakeresési módot az Emulátorban.

4. Másolja és illessze be az UUID-t a tesztbe webchat csatorna csevegőablakában. A csevegőablakban a "Munkamenethez csatolva, minden forgalom replikálva van ellenőrzésre" üzenet jelenik meg.

A robot hibakereséséhez küldjön üzeneteket a konfigurált csatorna csevegőablakában. A helyi Emulator automatikusan frissíti az üzeneteket a hibakeresés minden részletével. A robot üzenetállapotának vizsgálatához válassza a Robot állapota lehetőséget, és bontsa ki az értékeket a megfelelő JSON-ablakban.

Következő lépések

• Megtudhatja, hogyan végezhet hibakeresést a robotban átiratfájlok használatával.
• Megtudhatja, hogyan végezhet hibakeresést egy képesség- vagy képességfelhasználóban.