C# ActiveX控件开发完整Demo实战项目

本文还有配套的精品资源，点击获取

简介：ActiveX控件是微软基于COM模型推出的技术，广泛用于IE浏览器环境下的Web与桌面应用交互。本“C# ActiveX控件开发Demo”项目详细展示了如何使用C#语言结合.NET Framework实现ActiveX控件的创建、注册与调用。内容涵盖控件类定义、IObjectWithSite接口实现、安全机制处理及在HTML页面中的嵌入测试，帮助开发者掌握在传统企业级应用中集成可重用交互组件的关键技术，并理解其与现代Web技术的兼容性差异。

ActiveX控件与COM互操作：从C#开发到现代应用演进

在企业级内网系统中，你是否曾遇到过这样的场景——用户点击一个“上传加密文件”的按钮，弹出的不是普通的对话框，而是一个带有公司LOGO、支持UKey认证和本地签名功能的自定义界面？这背后很可能就是ActiveX控件在默默工作。

尽管HTML5和WebAssembly早已成为主流，但在金融、医疗、军工等对安全性和本地资源访问要求极高的领域，基于.NET平台开发的ActiveX控件依然扮演着不可替代的角色。它们像一座桥梁，连接着浏览器的安全沙箱与操作系统底层能力。今天我们就来深入这座“技术古迹”，看看如何用C#打造一个能在IE中稳定运行的ActiveX控件，并理解其背后的复杂机制。

---

当你打开Visual Studio准备新建项目时，别急着点“类库”。要让.NET代码被非托管环境调用，第一步就得选对模板—— Windows Forms 控件库 (.NET Framework) ，注意必须是Framework版本，而不是.NET Core或.NET 5+。为什么？

因为只有.NET Framework才内置了完整的COM互操作服务（COM Interop Services），它能自动为你的托管对象生成 COM可调用包装器 （CCW），就像给一位只会说中文的人配了个同声传译员，让他能在英文会议中发言。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <OutputType>Library</OutputType>
    <RegisterForComInterop>true</RegisterForComInterop>
    <PlatformTarget>x86</PlatformTarget>
  </PropertyGroup>
</Project>

上面这段 .csproj 配置看似简单，实则暗藏玄机：

• TargetFramework=net48 ：选择.NET 4.8不仅是出于兼容性考虑，更是因为它支持最新的运行时封送架构（RCW/CCW）。如果你尝试用.NET 2.0，可能会发现某些泛型类型无法正确导出。
• RegisterForComInterop=true ：这个开关太关键了！它能让Visual Studio在每次编译后自动执行 regasm.exe /codebase ，省去手动注册的麻烦。调试效率直接翻倍🚀
• PlatformTarget=x86 ：别小看这一行。如果目标机器使用的是32位IE（至今仍有大量企业环境如此），而你编译成x64，那控件加载就会失败，报错信息还特别模糊：“找不到指定模块”。

💡 小贴士：可以在“项目属性 → 生成”页面勾选“为COM互操作注册”，效果一样，但更直观。

flowchart TD
    A[启动 Visual Studio] --> B[新建项目]
    B --> C{选择模板}
    C --> D["Windows Forms 控件库 (.NET Framework)"]
    D --> E[设置目标框架为 .NET 4.8]
    E --> F[修改 PlatformTarget 为 x86]
    F --> G[启用 Register for COM interop]
    G --> H[添加 UserControl 派生类]
    H --> I[编写 UI 与逻辑代码]
    I --> J[生成并自动注册]
    J --> K[在 HTML 中通过 <object> 标签测试]

这个流程图看起来很标准，但实际开发中最容易卡住的地方往往出现在第J步——明明生成成功了，HTML里却提示“控件未加载”。这时候你需要检查三点：
1. 是否以管理员身份运行VS（注册表写入需要权限）
2. 防病毒软件有没有拦截 regasm.exe
3. IE的安全设置是否允许活动内容运行

---

光有正确的项目配置还不够，你还得告诉CLR：“请把我暴露出去！”默认情况下，即使你是 public 类，.NET也不会主动让COM知道你的存在。这就引出了两个至关重要的特性：

using System.Runtime.InteropServices;

[assembly: ComVisible(true)]
[assembly: Guid("A1B2C3D4-E5F6-7890-1234-567890ABCDEF")]

没错，这就是程序集级别的声明。 ComVisible(true) 相当于打开了整栋楼的大门，而 Guid 则是给这栋楼发了个唯一的身份证号。你可以把它想象成你在工商局注册公司时拿到的统一社会信用代码。

那么问题来了：是不是所有类都应该设为 ComVisible(true) ？当然不是！

我建议的做法是： 全局关闭可见性，在需要暴露的类上单独开启 。这样更安全，也便于维护。

// AssemblyInfo.cs
[assembly: ComVisible(false)]

// SampleActiveX.cs
[ComVisible(true)]
[Guid("12345678-ABCD-EF01-2345-6789ABCDEF01")]
[ProgId("MyCompany.ActiveXControl.Sample")]
[ClassInterface(ClassInterfaceType.AutoDual)]
public partial class SampleActiveX : UserControl
{
    public string Message { get; set; } = "Hello from ActiveX!";
}

这里有几个细节值得深挖：

• ProgId 是给人读的，比如JavaScript里可以用 new ActiveXObject("MyCompany...") 来创建实例。命名建议采用 厂商.组件名.版本 格式，例如 MyCorp.FileUploader.2 ，方便后续升级管理。
• ClassInterface(AutoDual) 会自动生成双接口，既支持早期绑定（高性能）又支持后期绑定（灵活）。但它有个致命缺点——一旦你修改了公共方法列表，旧脚本可能就崩了。所以在生产环境中，强烈建议定义自己的接口，避免依赖自动生成的契约。

说到注册，我们离不开那个经典命令：

regasm.exe SampleActiveX.dll /unregister
regasm.exe SampleActiveX.dll /codebase /tlb:SampleActiveX.tlb

其中 /codebase 是调试阶段的救命稻草。它会把DLL的完整路径写进注册表，解决“找不到模块”的常见错误。否则CLR只能靠GAC或探针路径去找程序集，很容易迷路😅

下面是几个常用参数的小抄：

参数	功能描述	是否推荐
/tlb	生成 .tlb 类型库文件，供非托管代码引用	✅ 强烈推荐
/codebase	写入DLL物理路径，解决“找不到模块”错误	✅ 调试阶段必用
/unregister	清除注册信息，用于重装前清理	✅ 维护必需
/register	注册所有 ComVisible=true 的类型	✅ 默认行为
/silent	静默模式，无提示输出	⚠️ 生产脚本可用

顺带提一句，如果你打算发布正式版，记得给程序集做 强名称签名 或 Authenticode签名 。否则IE高安全区会直接拦截加载，弹出“此控件未被信任”的警告。

---

现在我们来看看最核心的部分：.NET与COM之间到底是怎么通信的？

答案是： 双向包装机制 。

当一个托管对象被COM调用时，CLR会创建一个叫 COM Callable Wrapper （CCW）的东西作为代理；反过来，当你在C#中调用某个COM组件（比如Excel），.NET会生成一个 Runtime Callable Wrapper （RCW）帮你转发请求。

graph LR
    subgraph Unmanaged World [非托管环境]
        IE[Internet Explorer]
        Script[VBScript / JavaScript]
        CCW[COM Callable Wrapper]
    end

    subgraph Managed World [.NET Runtime]
        RCW[Runtime Callable Wrapper]
        DOTNETOBJ[托管 ActiveX 控件实例]
    end

    Script -->|CreateObject| CCW
    CCW <-->|封送调用| DOTNETOBJ
    IE -->|Load Object| CCW
    DOTNETOBJ -->|调用外部COM| RCW
    RCW --> ExternalCOM[其他COM组件]

举个例子，当你在JS中写下：

var ax = new ActiveXObject("MyCompany.ActiveXControl.Sample");
ax.Message = "Test";

实际发生了什么？

1. IE通过CLSID查找注册表；
2. 加载 mscoree.dll （.NET运行时宿主）；
3. 创建AppDomain并加载目标DLL；
4. CLR生成CCW实例；
5. 所有方法/属性调用经由 IDispatch::Invoke() 路由到.NET对象。

听起来很完美？其实不然。这种跨边界调用是有代价的——性能开销、生命周期管理复杂、GC无法及时感知COM引用计数变化，稍不注意就会导致内存泄漏 or 对象提前释放💥

所以我在设计控件时总会加上显式的资源管理：

public class SampleActiveX : UserControl, IDisposable
{
    private bool _disposed = false;

    protected override void Dispose(bool disposing)
    {
        if (!_disposed)
        {
            if (disposing)
            {
                components?.Dispose();
            }
            _disposed = true;
            base.Dispose(disposing);
        }
    }

    ~SampleActiveX()
    {
        Dispose(false);
    }
}

虽然Finalizer存在，但在COM环境下它的触发时机完全不可控。因此，关键资源一定要通过 Dispose 主动释放，不能依赖析构函数。

---

接下来聊聊UI部分。大多数ActiveX控件都需要可视化界面，所以我们通常继承 UserControl ：

[ComVisible(true)]
[Guid("12345678-ABCD-EF01-2345-6789ABCDEF01")]
public partial class AxLoginControl : UserControl
{
    private TextBox txtUsername;
    private MaskedTextBox txtPassword;
    private Button btnLogin;

    public AxLoginControl()
    {
        InitializeComponent();
        InitializeCustomComponents();
    }

    private void InitializeCustomComponents()
    {
        this.txtUsername = new TextBox() { Location = new Point(10, 10), Width = 200 };
        this.txtPassword = new MaskedTextBox() { Location = new Point(10, 40), Width = 200, PasswordChar = '*' };
        this.btnLogin = new Button() { Text = "登录", Location = new Point(10, 70) };

        this.btnLogin.Click += OnLoginButtonClick;

        this.Controls.Add(txtUsername);
        this.Controls.Add(txtPassword);
        this.Controls.Add(btnLogin);
    }

    private void OnLoginButtonClick(object sender, EventArgs e)
    {
        // 触发事件或调用外部服务
    }
}

这段代码没什么特别，但要注意几个坑：

• 所有UI操作必须在 STA线程 上执行。IE加载控件时会确保这一点，但如果你自己在后台线程创建实例，就得手动切回UI线程。
• 不要启用 DesignerSerializationVisibility.Content ，否则设计器会试图序列化整个子控件树，破坏COM契约。
• 属性暴露要用 [Browsable(true)] 控制是否在IDE属性窗口显示，这对调试很有帮助。

此外， UserControl 本身实现了不少OLE接口的包装，比如 IOleObject 、 IOleInPlaceObject ，这让IE能正确处理尺寸调整、焦点管理和上下文菜单。这些隐藏的能力其实是WinForms团队早就为你铺好的路👏

---

除了UI，控件还需要与容器深度交互。最常见的就是实现 IObjectWithSite 接口：

[ComImport]
[Guid("FC4801A3-2BA9-11CF-A229-00AA003D7352")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IObjectWithSite
{
    void SetSite([MarshalAs(UnmanagedType.IUnknown)] object pUnkSite);
    void GetSite(ref Guid riid, out IntPtr ppvSite);
}

public partial class AxLoginControl : UserControl, IObjectWithSite
{
    private object _site;

    public void SetSite(object site)
    {
        _site = site;
        // 可在此处查询 IServiceProvider 获取更多宿主服务
    }

    public void GetSite(ref Guid riid, out IntPtr ppvSite)
    {
        if (_site == null)
            throw new COMException("No site available", -2147221232); // E_FAIL

        ppvSite = Marshal.GetIUnknownForObject(_site);
        Marshal.AddRef(ppvSite);
    }
}

SetSite 方法会在控件插入文档时被IE调用，传入的 site 通常是WebBrowser控件本身。有了这个引用，你就可以做很多事：

• 获取当前URL
• 执行JavaScript
• 访问DOM元素
• 查询安全策略

比如你想知道当前页面属于哪个区域（本地、可信站点、互联网），就可以通过 IServiceProvider 去拿 IInternetSecurityManager ：

var sp = (IServiceProvider)_site;
Guid serviceGuid = SID.SID_InternetSecurityManager;
Guid interfaceGuid = typeof(IInternetSecurityManager).GUID;
sp.QueryService(ref serviceGuid, ref interfaceGuid, out object secMgr);

然后调用 ProcessUrlAction 判断是否允许执行敏感操作。这种机制让你的控件不仅能“看到”自己，还能感知整个浏览器环境，真正实现“情境感知”。

---

好了，UI和容器交互都搞定了，接下来轮到对外暴露功能——也就是属性、方法和事件。

先看属性。为了让脚本能读写，你得加上一堆元数据：

[ComVisible(true)]
[Guid("A7C58E5B-9F4D-4E2C-9B6A-1F8E9D7E2C5A")]
public partial class ScriptableControl : UserControl
{
    private string _displayName = "Default Control";

    [Browsable(true)]
    [Description("The display name shown in the UI.")]
    [DefaultValue("Default Control")]
    public string DisplayName
    {
        get { return _displayName; }
        set 
        { 
            _displayName = value;
            OnDisplayNameChanged(EventArgs.Empty);
        }
    }

    public event EventHandler DisplayNameChanged;
}

这几个特性各有用途：

• Browsable(true) ：决定该属性是否出现在Visual Studio工具箱的属性面板中，调试时非常有用。
• Description ：鼠标悬停时显示说明文字。
• DefaultValue ：帮助设计器判断是否需要序列化，默认值就不存了。

生成的IDL长这样：

[
    uuid(A7C58E5B-9F4D-4E2C-9B6A-1F8E9D7E2C5A),
    oleautomation,
    dual
]
interface IScriptableControl : IDispatch {
    [propget, id(1), helpstring("property DisplayName")] 
    HRESULT DisplayName([out, retval] BSTR* pVal);
    [propput, id(1), helpstring("property DisplayName")] 
    HRESULT DisplayName([in] BSTR newVal);
};

看到了吗？ string 被映射成了 BSTR ，这是COM的标准字符串类型。 .NET 自动完成了这一切，简直贴心❤️

---

再来说方法。参数封送是个大学问，稍不留神就会踩坑。

[ComVisible(true)]
public interface IOperationService
{
    int Add(int a, int b);

    bool ValidateInput(string input, out string errorMessage);

    [return: MarshalAs(UnmanagedType.IDispatch)]
    object GetDataRecord();
}

这里有几个重点：

• 输入参数尽量用基本类型（int、double、string），它们都能自动封送。
• out string 会被映射为 BSTR* ，由调用方负责释放内存。务必保证赋值时不为空指针。
• 返回 object 类型会变成 VARIANT ，支持多种子类型，但性能较低，慎用。

特别是最后一个 GetDataRecord ，返回的是 dynamic 对象，配合 [return: MarshalAs(UnmanagedType.IDispatch)] ，可以让JS动态访问属性：

var record = ctrl.GetDataRecord();
console.log(record.Name); // "Test Item"

这背后其实是 ExpandoObject + IDispatch 的魔法组合，堪称“弱类型救星”✨

graph TD
    A[JavaScript Call] --> B{Method Dispatch via IDispatch}
    B --> C[Managed Method in C#]
    C --> D[Parameter Marshaling]
    D --> E[Execute Business Logic]
    E --> F[Return Value Marshaling]
    F --> G[Result Back to Script]
    style A fill:#f9f,stroke:#333
    style G fill:#cff,stroke:#333

这张图清晰展示了从JS调用到.NET执行的完整链路。中间的“封送”环节由CLR全权负责，开发者几乎无需干预——除非你要传结构体或数组，那就得手动写 [MarshalAs] 了。

---

最后是事件系统。这是最难的部分，因为脚本环境不能直接订阅.NET事件。

解决方案是： 出站接口 （Outgoing Interface）+ 连接点 （Connection Points）

首先定义一个接口：

[ComVisible(true)]
[Guid("C3D5E6F7-G8H9-I1J2-K3L4-M5N6O7P8Q9R0")]
[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface IControlEvents
{
    [DispId(1)] void OnClick();
    [DispId(2)] void OnValueChanged(string newValue);
    [DispId(3)] void OnError(string message, int code);
}

关键点在于 InterfaceIsIDispatch ，表示该接口可通过后期绑定调用。每个方法要有固定的 DispId ，防止编译变动导致脚本绑定失效。

然后在类上标注：

[ComSourceInterfaces(typeof(IControlEvents))]
public partial class ScriptableButton : UserControl
{
    public event EventHandler Click;
    public event EventHandler<string> ValueChanged;
    public event EventHandler<ErrorEventArgs> Error;

    protected override void OnClick(EventArgs e)
    {
        Click?.Invoke(this, e);
        base.OnClick(e);
    }

    protected virtual void OnValueChanged(string newValue)
    {
        ValueChanged?.Invoke(this, newValue);
    }

    protected virtual void OnError(string message, int code)
    {
        Error?.Invoke(this, new ErrorEventArgs(null, code) { Message = message });
    }
}

注意：你不需要实现 IControlEvents 的方法体！ ComSourceInterfaces 的作用是在生成TLB时声明“我支持这些事件”，真正的分发由COM容器完成。

注册后生成的IDL片段如下：

[
    uuid(...),
    source,
    oleautomation
]
interface IControlEvents : IDispatch {
    [id(1)] HRESULT OnClick();
    [id(2)] HRESULT OnValueChanged([in] BSTR newValue);
    [id(3)] HRESULT OnError([in] BSTR message, [in] LONG code);
};

coclass ScriptableButton {
    [default] interface IScriptableButton;
    [source] interface IControlEvents;
}

看到 source 关键字了吗？这就是告诉系统：“我可以广播事件”。

前端绑定也很简单：

<object id="myButton" classid="clsid:A7C58E5B-..." width="100" height="30"></object>

<script type="text/javascript">
    function myButton::OnClick() {
        alert("Button clicked!");
    }
</script>

IE特有的 :: 语法用于声明事件处理器。当然也可以用 attachEvent 动态绑定：

ctrl.attachEvent("OnClick", function() {
    window.external.Notify("Clicked from JS");
});

不过后者已被废弃，仅作兼容之用。

---

部署环节才是真正的考验。就算代码写得再漂亮，部署失败一切归零。

核心命令还是那句：

regasm MyActiveXControl.dll /tlb:MyActiveXControl.tlb /codebase

如果要在设计时把控件拖到窗体上，还得用 AxImp.exe 生成包装器：

aximp MyActiveXControl.dll

它会产生两个文件：
- AxMyActiveXControl.dll ：可用于WinForm项目的宿主控件
- MyActiveXControlLib.dll ：类型库互操作程序集

HTML嵌入也很直接：

<object 
    id="myControl" 
    classid="clsid:ABCDEF12-3456-7890-ABCD-EF1234567890" 
    width="300" 
    height="200">
</object>

然后就能在JS中调用了：

var version = myControl.Version;
myControl.ShowMessage("Hello from JS!");

但别忘了检查IE设置：
- 启用“初始化和脚本运行”
- 将站点加入“可信站点”或“本地Intranet”
- 关闭增强安全配置（ESC）

否则哪怕注册成功，也会被拦下来。

graph TD
    A[编写C# UserControl] --> B[标记ComVisible(true)]
    B --> C[使用Regasm注册并生成TLB]
    C --> D[HTML中使用<object classid=>]
    D --> E[JavaScript调用属性/方法]
    E --> F[IE渲染并执行交互]
    F --> G{功能正常?}
    G -- 是 --> H[部署上线]
    G -- 否 --> I[检查签名、权限、注册状态]

这条路径上的每一个环节都可能出问题。建议写个批处理脚本一键部署：

@echo off
regasm /unregister MyControl.dll
regasm MyControl.dll /tlb /codebase
echo 控件已重新注册！
pause

省得每次都要手动敲命令。

---

回顾整个开发过程，你会发现ActiveX控件的本质是一场精巧的“跨界合作”：.NET提供强大的开发体验和UI能力，COM负责跨语言集成，而CCW/RCW则是背后的翻译官。虽然这项技术正逐步退出历史舞台，但在特定场景下，它依然是解决问题的最优解。

更重要的是，掌握这套机制能让你深刻理解 跨运行时互操作 的本质。无论是现在的WinRT、.NET MAUI，还是未来的混合架构，类似的挑战总会重现。今天的“古董技术”，或许正是明天创新的基石🧱

所以别急着淘汰它，先试着读懂它——毕竟，每一个老程序员的眼里，都藏着一段不会褪色的代码记忆😉

本文还有配套的精品资源，点击获取

简介：ActiveX控件是微软基于COM模型推出的技术，广泛用于IE浏览器环境下的Web与桌面应用交互。本“C# ActiveX控件开发Demo”项目详细展示了如何使用C#语言结合.NET Framework实现ActiveX控件的创建、注册与调用。内容涵盖控件类定义、IObjectWithSite接口实现、安全机制处理及在HTML页面中的嵌入测试，帮助开发者掌握在传统企业级应用中集成可重用交互组件的关键技术，并理解其与现代Web技术的兼容性差异。

本文还有配套的精品资源，点击获取