Bot Framework v4迁移：样式脚本文件变更及网站适配咨询

Hey there! Let's walk through what you need to know when migrating your Bot Framework v3 (and older) chatbot to v4, especially focusing on the frontend changes for your custom website using the old BotChat templates. I’ve been through this migration a few times, so here’s the breakdown:

First off, a big heads up: the old botchat.js/botchat.cs/styles.css files from v3 are deprecated in v4. Microsoft swapped them out for the official Microsoft Bot Framework Web Chat library, which is more flexible, secure, and modern. Let’s break down how each component changes:

botchat.cs (v3) → C# Backend Token Generation (v4) #

• In v3, botchat.cs handled server-side tasks like generating BotChat embeds or managing token exchanges.
• In v4, this file doesn’t have a direct replacement. Instead, you’ll need to write a custom C# controller endpoint that generates short-lived Direct Line tokens using your bot’s Direct Line secret. This endpoint will be called by your frontend to get a secure token (never expose your secret client-side—huge security risk!).

styles.css (v3) → Web Chat Customization (v4) #

• v3’s styles.css was a static sheet for the old BotChat widget. v4’s Web Chat uses either plain CSS with web-chat-* prefixed classes or CSS-in-JS via theme options.
• If you want to keep your site’s existing look, you’ll need to map your v3 CSS rules to v4’s class names. For example:
  • v3’s .wc-message becomes .web-chat__message
  • v3’s .wc-header is replaced by .web-chat__header (you can hide this if your site has its own chat header)
• Pro tip: Web Chat lets you pass a theme object directly in the initialization code to customize colors, fonts, and more—this is often cleaner than overriding CSS.

botchat.js (v3) → Web Chat Script (v4) #

• v3’s botchat.js was a monolithic script that handled rendering the widget and talking to the bot via Direct Line v3.
• In v4, you’ll use the Web Chat script (loaded via CDN or local bundle) which uses Direct Line v4. The initialization code is totally different—here’s a side-by-side:
  • v3 code example:

    BotChat.App({
      directLine: { secret: 'YOUR_DIRECT_LINE_SECRET' },
      user: { id: 'user-id' },
      bot: { id: 'bot-id' },
      resize: 'detect'
    }, document.getElementById('botchat'));
    

  • v4 equivalent (using CDN and secure token):

    async function initWebChat() {
      // Fetch token from your C# backend endpoint
      const res = await fetch('/api/directline/getToken', { method: 'POST' });
      const { token } = await res.json();
    
      window.WebChat.renderWebChat({
        directLine: window.WebChat.createDirectLine({ token }),
        userID: 'unique-user-id',
        username: 'You',
        botAvatarInitials: 'BOT'
      }, document.getElementById('webchat'));
    }
    
    initWebChat().catch(err => console.error('Web Chat init failed:', err));
    

• Important: v4 requires using a token (not a secret) in the frontend—this is non-negotiable for security.

Now let’s cover the changes you need to make to your existing Scripts and Content folders, plus other key tweaks:

Scripts Folder Changes #

1. Clean up old files: Delete botchat.js and any other v3-related scripts from your Scripts folder—they’re no longer needed.
2. Add Web Chat script: You have two options here:
   • CDN (recommended): Load the latest Web Chat script directly from Microsoft’s CDN. Add this to your HTML:

     <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
     

   • Local bundle: If you need offline access or want to customize the Web Chat source, download the latest bundle and add it to your Scripts folder.
3. Update initialization code: Replace your old BotChat setup with the v4 Web Chat code (like the example above). Make sure you’re fetching the token from your new C# endpoint.
4. Rewrite custom logic: If you had any custom message handlers or extensions tied to v3’s BotChat, rewrite them using Web Chat’s middleware system—it’s more powerful and flexible.

Content Folder Changes #

1. Replace styles.css: Remove the v3 styles.css and create a new CSS file for Web Chat customizations. Map your old styles to v4’s class names (as mentioned earlier). Here’s a quick example:

   /* Customize bot message bubbles */
   .web-chat__message__content {
     background-color: #0078d7;
     color: white;
     border-radius: 10px;
     padding: 10px 15px;
   }
   
   /* Customize user message bubbles */
   .web-chat__message__content--user {
     background-color: #e5e5ea;
     color: black;
   }
   

2. Optional: Use theme options: Instead of CSS, you can pass a theme object in the renderWebChat call to customize the widget’s look without writing extra CSS. For example:

   window.WebChat.renderWebChat({
     directLine: window.WebChat.createDirectLine({ token }),
     theme: {
       primaryBackgroundColor: '#0078d7',
       userAvatarBackgroundColor: '#e5e5ea',
       botAvatarBackgroundColor: '#0078d7'
     }
   }, document.getElementById('webchat'));
   

Additional Compatibility Checks #

• Direct Line Version: Make sure your C# v4 bot is configured to use Direct Line v4 (this is the default in the v4 SDK, but double-check your bot settings in the Azure Portal).
• Message Formats: v4 leans heavily on Adaptive Cards. If your bot sends custom cards (like Hero Cards), you’ll need to update them to Adaptive Cards or ensure they’re compatible with v4’s message schema.
• Responsiveness: Web Chat is mobile-friendly by default, but test your custom styles to make sure they work across all device sizes—v3’s BotChat was less reliable here.
• Security: Double-check that you’re never exposing your Direct Line secret in the frontend. Always use the backend token endpoint to generate short-lived tokens for each user.

内容的提问来源于stack exchange，提问作者Tanmayee