简介：围绕 Qt 动态库封装与 C# 跨语言调用，这套示例面向已具备 C++/Qt 基础、需要在 .NET 项目中复用 Qt 界面或核心能力的开发者，适用于界面组件复用、算法模块封装等场景，重点解决 C 接口设计、DLL 导出、P/Invoke 声明与调用约定匹配等工程问题。包内共 105 个文件，约 18.15MB，包含 Qt 工程源码与 pro 配置、C/C++ 头文件、编译生成的 dll/lib 及中间产物、C# 测试工程与 sln/csproj 文件，另有 qm 翻译资源和 qwinwidget 等相关组件，便于对照完整构建链路与运行依赖。已有 867 人学习下载，说明其在 Qt 与 C# 混合开发场景中具有较好的参考价值。读者可从中获得可运行的 Qt DLL 封装样例、C# 端 DllImport 调用代码、接口头文件以及测试项目组织方式，并据此排查导出符号、路径配置、调用失败等常见问题，对参数类型映射和错误处理亦有覆盖，适合作为跨语言集成的实践模板。
1. 把 Qt 界面做成 DLL 交给 C# 调用：先想清楚边界在哪里
接手一个桌面端项目时，前端界面用 C# 的 WinForm 或 WPF 写，但绘图、算法、设备通信这类活，团队里现成的代码全是 Qt 写的。重写一遍成本太高，最省事的做法就是把 Qt 那部分封装成 DLL，C# 直接调用。这套“QT封装成dll，C#调用测试例子”解决的就是这个场景：让 C++/Qt 的编译产物以标准 C 接口暴露出来，C# 用 P/Invoke 无痛接入。
适合谁看：手上有一份 Qt 代码想复用、又不想让 C# 侧引入一堆 C++ 依赖的学生做毕设、从业者做交付方案，都能照着这套结构走一遍。核心难点不在“怎么生成 dll”，而在于跨编译器、跨运行时的边界怎么划：哪些类型能过界，哪些绝对不能；字符串、结构体、回调函数这些老大难怎么处理。这些边界想清楚了，后面就是填代码。
2. 接口设计：为什么必须再加一层纯 C 导出
Qt 的类、信号槽、QString 这些，在 C# 那边是完全看不见的。直接在 dll 里导出 C++ 类，C# 根本没法用。所以架构上要做一件事：在 Qt 业务代码外面包一层纯 C 的导出函数，让 dll 对外只暴露extern "C"的函数和 POD 结构体。
2.1 三层结构划分
整体分成三层，每层职责单一，出问题时能快速定位是哪一层翻的车。
| 层级 | 位置 | 职责 | 对外暴露 |
|---|---|---|---|
| 业务层 | Qt/C++ 内部 | 算法、绘图、设备通信 | 不暴露 |
| 桥接层 | Qt DLL 内 | 把 C++ 类型转成 C 类型 | extern "C"函数 |
| 调用层 | C# 端 | P/Invoke 声明、封装成类 | 托管 API |
业务层随便用 Qt 的东西，QString、QList、信号槽都行；桥接层是唯一需要克制的部分，只用const char*、int、double、指针和不含 C++ 成员的结构体；调用层在 C# 里把裸函数再包成一个类，外面用起来就像普通 .NET 对象。
这样分层的好处是，哪天业务层要换实现，只要桥接层的函数签名不变，C# 那边一行都不用改。通常的做法是先把桥接层的头文件定下来，C# 和 C++ 两边照着同一份头文件各写各的，谁也别临时加参数。
2.2 导出函数的签名约定
桥接层的函数签名要遵守几条硬规矩，不然 C# 那边一定会在奇怪的地方崩溃。
// bridge_api.h —— C# 与 C++ 共同遵守的契约 #pragma once #ifdef BRIDGE_EXPORTS #define BRIDGE_API __declspec(dllexport) #else #define BRIDGE_API __declspec(dllimport) #endif // 全部用 C 链接，禁止 C++ 名称修饰 extern "C" { // 句柄：C# 侧用 IntPtr 接，内部就是业务对象的指针 typedef void* BridgeHandle; // 创建/销毁成对出现，谁创建谁负责释放 BRIDGE_API BridgeHandle Bridge_Create(void); BRIDGE_API void Bridge_Destroy(BridgeHandle h); // 字符串一律 UTF-8 + const char*，由调用方提供缓冲区 BRIDGE_API int Bridge_Process(BridgeHandle h, const char* input, char* output, int outputSize); // 返回错误码，0 表示成功，负数表示具体错误 BRIDGE_API int Bridge_GetLastError(BridgeHandle h, char* msg, int msgSize); }BridgeHandle用void*而不是直接暴露类指针，是为了让 C# 侧接触不到任何 C++ 类型信息。Bridge_Process的返回值用int表示实际写入长度或错误码，output缓冲区由 C# 分配，dll 只负责往里写，绝不返回内部缓冲区的指针——这是最常见的血泪教训，返回内部指针的写法在 C# 侧 GC 一动手就变成野指针。
Bridge_GetLastError单独拿出来，是因为很多调用失败时只想知道原因，不想去解析返回值。把错误信息做成一个可查询的接口，排查问题时舒服很多。
3. Qt 工程配置：编译选项和导出控制
桥接层代码写完，能不能编出 C# 认的 dll，全看工程配置。这里翻车的人特别多，最常见的是编出来一个 64 位 dll，C# 那边是 x86 进程，加载直接报BadImageFormatException。
3.1 .pro 文件的关键配置
Qt 用 qmake 的话，.pro里要显式声明这是一个库工程，并且定义导出宏。
# bridge.pro TEMPLATE = lib CONFIG += shared CONFIG -= app_bundle # 定义导出宏，配合头文件里的 BRIDGE_EXPORTS DEFINES += BRIDGE_EXPORTS # 只保留 C++11 以上，不要开异常跨边界 CONFIG += c++17 CONFIG -= exceptions_off QT -= gui # 桥接层本身不依赖 GUI，按需保留 QT += core TARGET = QtBridge DESTDIR = $$PWD/bin # 关键：显式指定平台与架构，64 位就写死 win32 { CONFIG += windows QMAKE_TARGET.arch = x86_64 }TEMPLATE = lib加CONFIG += shared是生成动态库的必要组合，缺一个就变成静态库，C# 那边根本加载不了。QT -= gui是能省则省——桥接层如果你确实只做算法，不碰界面，就别链 QtGui，dll 体积能小一大截，部署时也少带几个 Qt 的依赖 dll。
QMAKE_TARGET.arch这行别嫌它啰嗦，血泪经验：qmake 在某些环境里会跟着宿主机的环境变量跑到 32 位去，编出来的 dll 和 C# 的 AnyCPU/x64 一撞就是加载失败。显式写死能省下半天排查时间。
如果用的是 CMake，等价写法是add_library(QtBridge SHARED ...)配target_compile_definitions(QtBridge PRIVATE BRIDGE_EXPORTS)，架构用CMAKE_GENERATOR_PLATFORM=x64或者直接在命令行指定。
3.2 导出符号的验证方法
dll 编出来了别急着扔给 C#，先用工具确认导出表对不对。Visual Studio 自带的dumpbin就能看。
# 列出 dll 的导出函数，确认名字没有被 C++ 修饰 dumpbin /exports QtBridge.dll # 期望看到的样子（C 链接，名字干净） # 1 0 00011230 Bridge_Create # 2 0 00011280 Bridge_Destroy # 3 0 000112D0 Bridge_Process如果看到的是?Bridge_Create@@YAPEAXXZ这种带问号和@@的名字，说明extern "C"没生效，或者被某个 C++ 头文件污染了。这时候 C# 里按Bridge_Create声明入口点必然找不到，EntryPointNotFoundException就是这么来的。
还有一种情况：导出表里名字是对的，但带了个_Bridge_Create@0的后缀，那是__stdcall调用约定加上去的。C# 侧DllImport要么把CallingConvention对上，要么干脆统一用__cdecl（默认约定），桥接层别乱加__stdcall，能少一类问题。
3.3 依赖运行库的处理
Qt 的 dll 本身依赖 Qt5Core.dll 或 Qt6Core.dll，还有 C++ 运行库。C# 程序启动时如果找不到这些依赖，加载 QtBridge.dll 会直接失败，报错信息还特别含糊。
部署时的通常做法是：把 QtBridge.dll 和它依赖的 Qt Core dll、平台插件一起放到 C# 输出目录下。如果不想让用户装 Qt 环境，可以用静态链接 Qt 的方式编桥接层（CONFIG += static配合静态版 Qt），代价是 dll 体积变大，但部署简单，适合交付给别人的场景。
提示：调试阶段如果遇到“找不到指定模块”，先用 Dependencies 或 Process Monitor 看加载 QtBridge.dll 时缺哪个文件，比猜快得多。
4. C# 侧调用：P/Invoke 声明与资源管理
dll 备好了，C# 这边要做的就是把裸函数包成一个用起来顺手的托管类。声明本身不难，难在字符串编码、句柄生命周期和异常保护。
4.1 P/Invoke 声明与字符串传递
using System; using System.Runtime.InteropServices; using System.Text; public sealed class QtBridge : IDisposable { private const string DllName = "QtBridge.dll"; // 句柄用 IntPtr 承接 C++ 的 void* [DllImport(DllName, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)] private static extern IntPtr Bridge_Create(); [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)] private static extern void Bridge_Destroy(IntPtr handle); // 字符串走 UTF-8，输出缓冲区由 C# 分配 [DllImport(DllName, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)] private static extern int Bridge_Process( IntPtr handle, [MarshalAs(UnmanagedType.LPUTF8Str)] string input, byte[] output, int outputSize); private IntPtr _handle; private bool _disposed; public QtBridge() { _handle = Bridge_Create(); if (_handle == IntPtr.Zero) throw new InvalidOperationException("Bridge_Create 返回空句柄"); } public string Process(string input) { // 先给一个足够大的缓冲，返回值是实际长度 var buffer = new byte[4096]; int len = Bridge_Process(_handle, input, buffer, buffer.Length); if (len < 0) throw new InvalidOperationException($"处理失败，错误码 {len}"); // 只解实际写入的部分，别把整块缓冲都转成字符串 return Encoding.UTF8.GetString(buffer, 0, len); } public void Dispose() { if (_disposed) return; if (_handle != IntPtr.Zero) { Bridge_Destroy(_handle); _handle = IntPtr.Zero; } _disposed = true; } }几个参数得说清楚。CallingConvention.Cdecl必须和 C++ 侧一致，默认的Winapi在 32 位下是__stdcall，不一致就会在调用时栈失衡，表现为莫名其妙的崩溃。CharSet.Ansi配UnmanagedType.LPUTF8Str是让 .NET 把 C# 的 string 按 UTF-8 编组过去，别用CharSet.Unicode硬塞 UTF-16，C++ 那边按char*读会读出一堆乱码。
byte[] output这个参数在 .NET 里会被固定住传给非托管代码，是安全的；但如果你图省事改用StringBuilder接返回值，就得注意容量和结尾的\0，容量给小了 dll 写越界就是内存踩踏，这类翻车事后很难查。
4.2 句柄生命周期与异常保护
句柄这东西最怕两件事：忘了释放、释放了还接着用。C# 这边用IDisposable包住是基本操作，再配上using语句，正常路径基本不会漏。
// 推荐用法：作用域结束自动释放 using (var bridge = new QtBridge()) { string result = bridge.Process("test input"); Console.WriteLine(result); }要防的是异常路径。如果Process中途抛异常，using依然会调Dispose，所以Bridge_Destroy里千万别再做可能抛异常的操作，纯释放就好。另外一个坑是 C++ 侧的异常不能跨 dll 边界往外抛，桥接层里所有函数都要用try/catch(...)兜住，转成返回错误码。一旦让 C++ 异常穿过 P/Invoke 边界，C# 进程会以访问冲突的形式直接挂掉，连堆栈都看不到，典型的黑匣子现场。
5. 避坑与排查：三类最容易翻车的问题
这套方案跑通不难，难的是第一次跑不通时不知道错在哪。下面三条是踩得最多的，按“现象 → 原因 → 解决”的顺序理一遍。
5.1 加载 dll 报 BadImageFormatException
现象：C# 程序一 new 那个封装类就抛BadImageFormatException，提示“试图加载格式不正确的程序”。
原因：位数不匹配。Qt 编出来的是 64 位 dll，C# 项目是 x86；或者反过来。另一种可能是 dll 依赖了 32 位的 Qt Core。
解决：先把 C# 项目的平台目标显式设成 x64（或者 x86），别留 AnyCPU；再用dumpbin /headers QtBridge.dll确认machine (x64)那行。两边对齐后问题就消失了。养成习惯：桥接工程和调用工程在同一个解决方案里，平台配置一起改，别各配各的。
5.2 字符串中文变乱码或截断
现象：传英文正常，传中文到 C++ 侧变成问号或者乱码；或者长一点的字符串后半段丢了。
原因：编码不一致（C# 侧按 UTF-16 编组过去，C++ 按 char* 读），或者缓冲区容量不够，dll 写满了却没告诉调用方需要多长。
解决：统一 UTF-8，C# 侧用UnmanagedType.LPUTF8Str，C++ 侧收到const char*后用QString::fromUtf8转换。缓冲区不够的情况，让Bridge_Process在返回负数错误码时同时通过Bridge_GetLastError告知所需长度，C# 侧扩容后重试一次。
5.3 调用几次后进程崩溃
现象：单次调用正常，循环调几百次之后随机崩溃，崩溃位置还不固定。
原因：dll 返回了内部缓冲区的指针，C# 侧拿Marshal.PtrToStringAnsi转完之后，C++ 内部那块内存被覆盖或释放，指针就悬空了。也可能是句柄被提前释放还在被使用。
解决：桥接层只往调用方给的缓冲区里写，绝不返回内部指针；句柄的创建和销毁严格配对，用IDisposable管起来。如果确实需要 dll 分配内存返回，就必须再提供一个Bridge_Free让 C# 侧显式释放，别指望两边 GC 能互相理解。
6. 验收与答辩：用一份最小可复现的测试工程说话
方案交出去，别人第一句会问“能用吗、怎么证明”。我的做法是准备一份最小测试工程：一个 Qt 桥接库 + 一个 C# 控制台程序，二十来行代码，双击就能跑，覆盖创建、处理、释放三条路径，外加一个中文输入和一次错误码触发。答辩或交付时现场跑一遍，比任何 PPT 都有说服力。
具体验收可以按这张表逐项过：
| 验收项 | 检查方法 | 通过标准 |
|---|---|---|
| 导出符号 | dumpbin /exports | 三个函数名无 C++ 修饰符 |
| 位数一致 | 看 C# 项目平台 + dll 头信息 | 均为 x64 |
| 基本调用 | 控制台跑 Process("hello") | 返回预期结果 |
| 中文传递 | Process("测试中文") | 无乱码、不截断 |
| 资源释放 | 循环调用 1000 次后退出 | 进程不崩、无泄漏告警 |
| 异常路径 | 传入触发错误的参数 | 返回负数错误码而非崩溃 |
| 部署干净 | 拷到无 Qt 环境的机器上跑 | 带上依赖 dll 后能启动 |
循环一千次那条特别值得加，很多悬空指针问题单次调用根本暴露不出来。部署干净那条也别省，开发机上什么都有，换个环境就翻车的情况太多了。
答辩时如果被问“为什么不直接暴露 C++ 类”，就把第 2 章那套分层讲一遍：C# 不认识 C++ 的类布局，虚表、名称修饰、异常模型全都对不上，纯 C 接口是两边唯一能握手的地方。被问“性能损耗大吗”，就指一下缓冲区方案和 UTF-8 编组，说明只在边界做一次转换，业务计算都在 C++ 里跑，影响可以忽略。
从那以后我每次做跨语言调用，都会先写一份最小测试工程再动手写业务，验收表也一起建好——边界问题在二十行代码里暴露，比在几千行业务里暴露便宜太多。希望帮到你。
本文还有配套的精品资源，点击获取
