C#与JavaScript交互：怎么将C#对象注入JS执行上下文

将 C# 原生对象直接挂载到 Web 容器的 JavaScript 全局作用域中，是现代桌面混合开发（如 WPF、WinForms 结合 Web 前端 UI）最直接的通讯手段。它的核心机制是在浏览器内核与宿主运行时之间建立进程间 RPC 通道，使前端代码能像调用普通 JS 对象方法一样，直接触发 .NET CLR 中的实例方法并接收返回结果。在主流的 WebView2（基于 Chromium）和 CefSharp 中，分别依赖 AddHostObjectToScript 与 RegisterJsObject / RegisterAsyncJsObject 来完成对象投影。

一、对象注入的运行架构与桥接原理

很多初学者误以为对象注入是将 C# 的 IL 代码或内存直接复制到了 JavaScript 引擎内部，其实不然。Chromium 渲染引擎（Render Process）与宿主程序（Browser/Host Process）处于不同进程。注入动作实际上是在宿主进程中保留 C# 对象的真实引用，而在渲染进程的 JavaScript window 上挂载一个代理（Proxy）对象。

当前端调用注入对象的方法时，JavaScript 引擎拦截该调用，序列化参数并通过进程间通信（IPC）将调用请求派发到宿主进程；C# 端反射调用实际方法后，将返回值通过 IPC 回传并转化为 JavaScript 的 Promise 或直接结果。

图 1：C# 宿主运行时与 Chromium V8 执行上下文之间的跨进程代理通信架构

二、基于 Microsoft WebView2 的注入实现步骤

WebView2 是目前 Windows 平台混合开发的首选组件。在 WebView2 中注入对象要求 C# 类必须支持 COM 互操作，方法需要暴露为公共成员。

1. 声明并定义注入类

首先定义一个服务类。为了让 WebView2 底层能通过 COM 机制访问到对象的方法与属性，必须引入 System.Runtime.InteropServices，并为类添加 [ClassInterface(ClassInterfaceType.AutoDual)] 和 [ComVisible(true)] 特性：

using System;
using System.Runtime.InteropServices;
using System.Threading.Tasks;

namespace DesktopApp.Bridge
{
    [ClassInterface(ClassInterfaceType.AutoDual)]
    [ComVisible(true)]
    public class NativeBridgeService
    {
        public string GetAppVersion()
        {
            return "v1.4.0-release";
        }

        public async Task<string> FetchDataAsync(string queryId)
        {
            await Task.Delay(200); // 模拟耗时任务
            return $"Query[{queryId}] Result from C#";
        }

        public int Calculate(int a, int b)
        {
            return a + b;
        }
    }
}

2. 在宿主代码中完成注入

注入时机非常关键。必须在 WebView2 初始化完成（CoreWebView2InitializationCompleted）之后、且通常在页面导航完成前注册。可以通过 CoreWebView2.AddHostObjectToScript 注册对象：

using Microsoft.Web.WebView2.Core;
using System.Windows;

namespace DesktopApp
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            InitializeWebViewAsync();
        }

        private async void InitializeWebViewAsync()
        {
            // 确保 CoreWebView2 就绪
            await webView.EnsureCoreWebView2Async(null);

            // 实例化桥接服务
            var bridge = new NativeBridgeService();

            // 注册到 JS 上下文，别名为 nativeService
            webView.CoreWebView2.AddHostObjectToScript("nativeService", bridge);

            // 导航到目标网页
            webView.CoreWebView2.Navigate("https://app.local/index.html");
        }
    }
}

3. 在前端 JavaScript 中调用

在前端上下文中，注入的对象默认暴露在 chrome.webview.hostObjects.nativeService 路径下。WebView2 默认将所有调用包装为异步 Promise：

// 异步调用 C# 同步/异步方法
async function testBridge() {
  const bridge = chrome.webview.hostObjects.nativeService;

  // 即使 C# 是同步方法，JS 端默认也是 Promise
  const version = await bridge.GetAppVersion();
  console.log("App Version:", version);

  const sum = await bridge.Calculate(15, 27);
  console.log("15 + 27 =", sum);

  const data = await bridge.FetchDataAsync("item-001");
  console.log("Data:", data);
}

如果希望在前端像同步对象一样访问属性，可以使用 WebView2 提供的同步代理对象 chrome.webview.hostObjects.sync.nativeService，但强烈建议优先使用异步形式，避免因宿主主线程阻塞导致前端界面无响应。

图 2：WebView2 对象注入的标准实施四步法

三、常见参数类型映射与转换规则

跨语言交互时，数据类型的兼容性是造成运行时异常最集中的环节。由于 JavaScript 是动态弱类型，而 C# 是强类型，底层桥接器会对参数进行自动封送转换。

• 基本类型：string、int、double、bool 在两端完全无缝映射，自动转为 JS 的对应 Primitive 类型。
• 日期类型：JS 传过来的 Date 对象会被转为 C# 的 DateTime，建议在网络层统一使用 ISO-8601 字符串传递，避免时区与序列化歧义。
• 复合对象与数组：若传递 JS 对象，C# 端接收参数可以定义为具体的 DTO 模型、dynamic 或 System.Text.Json.Nodes.JsonNode。推荐直接传递 JSON 序列化字符串，在两端显式反序列化，解耦结构依赖。
• 回调函数（Callback）：可以将 JavaScript 的回调函数作为参数传入 C#。C# 端将其捕获为 COM 接口或派遣对象，但必须注意垃圾回收机制：若 C# 未持有强引用，回调可能失效。

图 3：跨边界核心类型映射关系与边界行为

四、安全边界与关键排坑事项

将宿主原生对象暴露给 Web 内容是一项高危操作。如果页面能够加载不可控的第三方脚本（或者遭受 XSS 注入），攻击者可能通过反射或暴露的方法越权访问宿主系统的文件、进程或敏感网络。

1. 控制暴露面：定义专用的桥接类（如 WebBridgeFacade），不要直接注册包含系统级调用（如 File.Delete、Process.Start）的服务。所有传入参数必须先做格式和路径越界验证。
2. 避免死锁：在 WinForms/WPF 中，如果在 UI 线程上以同步等待（如 .Result 或 .Wait()）的方式调用异步桥接逻辑，极易导致主消息循环死锁。统一使用 async/await。
3. 页面刷新注入失效问题：对于频繁单页跳转或多页面切换的应用，如果使用静态注册，可以在 NavigationStarting 事件中确认对象是否已重新挂载，或者在初始化阶段统一注入。
4. 同源隔离：限制可以调用原生对象的 URL 白名单。在 WebView2 中，可以在调用注入前检查 webView.Source，防止非受信任站点访问 chrome.webview.hostObjects。

图 4：C# 对象暴露到 JS 时的安全性与防御性设计原则总结