Men-debug bot dengan middleware inspeksi

BERLAKU UNTUK: SDK v4

Artikel ini menjelaskan cara men-debug bot menggunakan middleware inspeksi. Fitur ini memungkinkan Emulator Kerangka Kerja Bot untuk men-debug lalu lintas ke dalam dan ke luar bot, dan melihat status bot saat ini. Anda dapat menggunakan pesan pelacakan untuk mengirim data ke Emulator lalu memeriksa status bot Anda dalam giliran percakapan tertentu.

Kami menggunakan EchoBot yang dibuat secara lokal menggunakan Bot Framework v4 di mulai cepat Membuat bot untuk menunjukkan cara men-debug dan memeriksa status pesan bot. Anda juga dapat Men-debug bot menggunakan IDE atau Debug dengan Bot Framework Emulator, tetapi untuk men-debug status Anda perlu menambahkan middleware inspeksi ke bot Anda. Sampel bot inspeksi tersedia untuk C#, JavaScript, Java, dan Python.

Catatan

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Power Virtual Agents dan baca tentang memilih solusi chatbot yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

Prasyarat

• Pengetahuan tentang bot Middleware dan Mengelola status
• Pengetahuan tentang cara Men-debug bot SDK-first dan Uji dan debug dengan Emulator
• Penginstalan Emulator Kerangka Kerja Bot
• Ngrok penginstalan (jika Anda ingin men-debug bot yang dikonfigurasi di Azure untuk menggunakan saluran lain)
• Salinan sampel bot inspeksi untuk C#, JavaScript, Java, atau Python

Memperbarui Emulator Anda ke versi terbaru

Sebelum menggunakan middleware inspeksi bot untuk men-debug bot Anda, perbarui Emulator Anda ke versi 4.5 atau yang lebih baru. Periksa versi terbaru untuk pembaruan.

Untuk memeriksa versi Emulator Anda, pilih Bantuan, lalu Tentang di menu. Anda akan melihat versi Emulator Anda saat ini.

Memperbarui kode bot Anda

C#

Status inspeksi dan middleware inspeksi dikonfigurasi dalam file Startup.cs lalu digunakan oleh adaptor.

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

Perbarui kelas bot dalam 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

Sebelum memperbarui kode bot Anda, perbarui paketnya ke versi terbaru dengan menjalankan perintah berikut di terminal Anda:

npm install --save botbuilder@latest

Kemudian Anda perlu memperbarui kode bot JavaScript Anda sebagai berikut. Anda dapat membaca selengkapnya di sini: Perbarui kode bot Anda atau lihat sampel middleware Inspeksi di GitHub.

index.js

Siapkan status inspeksi dan tambahkan middleware inspeksi ke adaptor dalam 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

Perbarui kelas bot dalam 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

Siapkan status inspeksi dan tambahkan middleware inspeksi ke adaptor dalam file Application.java . Status inspeksi diatur dengan menyediakan Spring @Bean baru untuk menyediakan BotFrameworkHttpAdapter yang diatur menjadi @Primary sehingga akan menimpa BotFrameworkHttpAdapter default yang disediakan oleh kelas dasar BotDependencyConfiguration. Lihat pembaruan kode di bawah ini atau lihat sampel middleware Inspeksi di 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 diimplementasikan sebagai bagian dari paket com.microsoft.bot.integration dan dapat ditinjau dari kode sumber Java SDK.

Perbarui kelas bot dalam 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

Sebelum memperbarui kode bot Anda, instal paket PyPI yang diperlukan dengan menjalankan perintah berikut di terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Siapkan status inspeksi dalam file app.py dengan menambahkan middleware ke adaptor.

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)

Perbarui kelas bot dalam file echo_bot.py .

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

Menguji bot Anda secara lokal

Setelah memperbarui kode, Anda dapat menjalankan bot secara lokal dan menguji fitur penelusuran kesalahan menggunakan dua Emulator: satu untuk mengirim dan menerima pesan, dan yang lainnya untuk memeriksa status pesan dalam mode debugging. Untuk menguji bot Anda secara lokal:

1. Buka direktori bot Anda di terminal dan jalankan perintah berikut untuk menjalankan bot Anda secara lokal:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Buka Emulator Anda. Pilih Buka Bot. Isi URL Bot dengan http://localhost:3978/api/messages dan nilai MicrosoftAppId dan MicrosoftAppPassword. Jika Anda memiliki bot JavaScript, Anda dapat menemukan nilai-nilai ini di file .env bot Anda. Jika Anda memiliki bot C#, Anda dapat menemukan nilai-nilai ini dalam file appsettings.json . Untuk bot Java, Anda dapat menemukan nilai-nilai ini dalam file application.properties . Pilih Sambungkan.

3. Sekarang buka jendela Emulator lain. Jendela Emulator kedua ini akan berfungsi sebagai debugger. Ikuti instruksi seperti yang dijelaskan pada langkah sebelumnya. Centang Buka dalam mode debug lalu pilih Koneksi.

4. Pada titik ini Anda akan melihat perintah dengan pengidentifikasi unik (/INSPECT attach <identifier>) di Emulator debugging Anda. Salin seluruh perintah dengan pengidentifikasi dari Emulator debugging dan tempelkan ke kotak obrolan Emulator pertama.

   Catatan

   Pengidentifikasi unik dihasilkan setiap kali Emulator diluncurkan dalam mode debug setelah Anda menambahkan middleware inspeksi dalam kode bot Anda.

5. Sekarang Anda dapat mengirim pesan di kotak obrolan Emulator pertama Anda dan memeriksa pesan di Emulator penelusuran kesalahan. Untuk memeriksa status pesan, pilih Status Bot di Emulator debugging dan buka nilai di jendela JSON kanan. Anda akan melihat status bot Anda di Emulator debugging:

   

Memeriksa status bot yang dikonfigurasi di Azure

Jika Anda ingin memeriksa status bot yang dikonfigurasi di Azure dan tersambung ke saluran (seperti Teams) Anda harus menginstal dan menjalankan ngrok.

Menjalankan ngrok

Pada titik ini, Anda telah memperbarui Emulator ke versi terbaru dan menambahkan middleware inspeksi dalam kode bot Anda. Langkah selanjutnya adalah menjalankan ngrok dan mengonfigurasi bot lokal Anda. Sebelum menjalankan ngrok, Anda perlu menjalankan bot Anda secara lokal.

Untuk menjalankan bot Anda secara lokal:

1. Buka folder bot Anda di terminal dan atur pendaftaran npm Anda untuk menggunakan build terbaru

2. Jalankan bot Anda secara lokal. Anda akan melihat bot Anda mengekspos nomor port seperti 3978.

3. Buka prompt perintah lain dan buka folder proyek bot Anda. Jalankan perintah berikut:

   ngrok http 3978
   

4. ngrok sekarang terhubung ke bot yang berjalan secara lokal. Salin alamat IP publik aman (HTTPS).

   

Memperbarui sumber daya bot Anda

Sekarang setelah bot lokal Anda tersambung ke ngrok, Anda dapat mengonfigurasi sumber daya bot Anda di Azure untuk menggunakan URL ngrok.

1. Buka sumber daya bot Anda di Azure. Di menu sebelah kiri, di bawah Pengaturan, pilih Konfigurasi.

   1. Atur titik akhir Olahpesan ke alamat IP ngrok yang Anda salin. Jika perlu, tambahkan /api/messages setelah alamat IP. Contohnya,https://e58549b6.ngrok.io/api/messages.

   2. Pilih Aktifkan Titik Akhir Streaming.

      

   3. Pilih Terapkan untuk menyimpan perubahan.

      Tip

      Jika Terapkan tidak diaktifkan, Anda dapat menghapus centang Aktifkan Titik Akhir Streaming dan pilih Terapkan, lalu centang Aktifkan Titik Akhir Streaming dan pilih Terapkan lagi. Anda perlu memastikan bahwa Aktifkan Titik Akhir Streaming dicentang dan konfigurasi titik akhir disimpan.

2. Buka grup sumber daya bot Anda.

   1. Pilih Penyebaran, lalu pilih sumber daya bot yang sebelumnya berhasil disebarkan. Pilih Templat dari menu sebelah kiri untuk mendapatkan MicrosoftAppId dan MicrosoftAppPassword untuk aplikasi web yang terkait dengan bot Anda.

      

   2. Perbarui file konfigurasi bot Anda (appsettings.json untuk C#, atau .env untuk JavaScript) dengan MicrosoftAppId dan MicrosoftAppPassword.

3. Mulai Emulator Anda, pilih Buka Bot, dan masukkan http://localhost:3978/api/messages di URL Bot. Isi ID Aplikasi Microsoft dan kata sandi Aplikasi Microsoft dengan MicrosoftAppId dan MicrosoftAppPassword yang sama dengan yang Anda tambahkan ke file konfigurasi bot kami. Kemudian pilih Sambungkan.

4. Bot Anda yang sedang berjalan sekarang tersambung ke sumber daya bot Anda di Azure. Untuk menguji bot Anda di Azure di Web Chat, buka sumber daya bot Anda, pilih Uji di Web Chat, dan kirim pesan ke bot Anda.

Aktifkan mode penelusuran kesalahan

1. Di Emulator Anda, pilih Debug, lalu Mulai Penelusuran Kesalahan.

2. Masukkan alamat IP ngrok (jangan lupa untuk menambahkan /api/messages) untuk URL Bot (misalnya, https://e58549b6.ngrok.io/api/messages).

   1. Untuk ID Aplikasi Microsoft, masukkan ID aplikasi bot Anda.
   2. Untuk kata sandi Aplikasi Microsoft, masukkan rahasia aplikasi bot Anda.
   3. Pastikan Buka dalam mode debug juga dicentang.
   4. Pilih Sambungkan.

3. Dengan mode debugging diaktifkan, Emulator menghasilkan UUID. UUID adalah ID unik yang dihasilkan setiap kali Anda memulai mode debugging di Emulator Anda.

4. Salin dan tempel UUID ke kotak Uji di obrolan Web Chat untuk kotak obrolan saluran Anda. Anda akan melihat pesan "Terlampir ke sesi, semua lalu lintas sedang direplikasi untuk diperiksa" di kotak obrolan.

Anda dapat mulai men-debug bot dengan mengirim pesan di kotak obrolan saluran yang dikonfigurasi. Emulator lokal Anda akan secara otomatis memperbarui pesan dengan semua detail untuk penelusuran kesalahan. Untuk memeriksa status pesan bot Anda, pilih Status Bot dan buka nilai di jendela JSON kanan.

Langkah berikutnya

• Pelajari cara Men-debug bot Anda menggunakan file transkrip.
• Pelajari cara Men-debug keterampilan atau konsumen keterampilan.