简介WTL10.0是微软轻量级C库的最终版本专门针对Visual Studio 2019做了适配与优化面向希望直接调用Windows API、构建高效小巧桌面程序的C开发者。压缩包共收纳296个文件整体约704KB其中104个头文件与39个C源文件构成核心库另有sln、vcxproj等多套示例工程bmp、ico、rc等界面资源以及html、txt、hhc等文档索引方便在VS2019中安装、编译和查阅。目前已有325人学习下载。包内附带了安装向导、示例代码、完整的头文件与库文件、更新日志和API参考文档开发者可据此快速搭好WTL开发环境借助模板类、消息映射和Unicode支持编写出结构清晰、便于维护的Windows程序同时它保留了对ATL、MFC乃至Boost的良好兼容性适合具备C基础、希望在轻量框架下替代MFC的中高级开发者。1. WTL 10.0 最终版本为什么 VS2019 用户还在翻它的牌2019 年 10.0 最终版本发布之后WTL 进入了长期维护模式但这恰恰是它适合当下的原因API 不再大幅变动坑基本被人踩平了。对还在 VS2019 上维护内网工具、设备上位机程序、插件面板的 C 工程师来说WTL 10.0 是一个介于 MFC 和裸 Win32 之间的舒服位置——不需要分发运行库一个 exe 几百 KB编译快界面编写又比手写 Win32 消息循环省一半力气。这篇文章直接以 VS2019 为环境把 WTL 10.0 的依赖链、工程配置、消息映射、对话框和常见编译坑一次讲透。2. 从 ATL 到 WTL 10.0搞懂依赖链避开 VS2019 的 ATL 版本坑2.1 WTL 不是又一个 UI 库它是 ATL 的“民间官方扩展”先把这个关系说清楚不然配环境时你会一脸茫然。ATLActive Template Library是微软做 COM 组件用的轻量模板库本身不提供窗口框架。WTL 的全称是 Windows Template Library它做的事情就是把 ATL 的模板思路延伸到窗口上以CWindow为根让窗口类、对话框类、控件封装全部变成模板类和宏的组合。跟 MFC 比WTL 最大的不同在于没有运行时依赖。MFC 程序不管动态还是静态链接编译产物里都带着一整套类库的痕迹升级 VS 版本时经常要跟着改。WTL 程序编译时只依赖 ATL 头文件和系统库运行时不需要分发任何 WTL 动态库发布一个 exe 就完事。这对我来说是最有吸引力的一点内网机器上往往缺少各种 VC 运行库而 WTL 程序双击就跑。下面是三个方案在实践中的对比你判断自己该不该转对比项MFCWTL裸 Win32运行时依赖MFC DLL 或静态运行库仅系统 DLL无界面代码量少向导强较少宏简洁多全手写产物体积大小最小但代码量失控控件封装全面够用无消息处理消息表 向导消息映射宏手工 switch学习曲线中中高高我早期做过一个监控小工具MFC 版本发布后要带 3 个 DLL换到 WTL 后变成一个 400 KB 的单 exe客户拷贝直接跑。就这一条足够让老项目翻牌子。2.2 为什么说 10.0 是“最终版本”VS2019 兼容性之外的事实清单WTL 的版本线从 7.x 走到 8.x、9.x到 10.0 时官方明确把适配重点放到了 VS2019 上。当时的核心问题不是 WTL 代码本身而是 ATL 的版本检测。WTL 头文件里大量代码靠_ATL_VER这个宏判断当前 ATL 支持哪些特性VS2019 的 v142 工具集带的 ATL 版本号比 WTL 9.1 预期的高导致条件编译走错分支出现一批莫名其妙的编译错误。10.0 做了三件关键事一是重写了 ATL 版本检测逻辑让 v142 工具集能正常通过二是修了一批 64 位编译告警老代码里GetWindowLong转GetWindowLongPtr的隐患被处理三是对 Windows 10 SDK 新增的头文件和控件做了适配。之后项目进入修复式维护没有继续规划 11所以“最终版本”这个说法是准确的。这里有个容易被忽略的点WTL 10.0 的代码风格还是老式的 C98/03 那一套编译不需要开 C11/C14。你在 VS2019 里用默认标准编译完全没问题反而别随手开/std:clatest去追新标准开了之后某些第三方库的告警会盖住你自己的问题。2.3 VS2019 必须先装 ATL 组件否则头文件都打不开WTL 头文件的第一行几乎都带着#include atlbase.h而这个atlbase.h不在 Windows SDK 里属于 VS 的 ATL 组件。VS2019 安装时默认“使用 C 的桌面开发”工作负载并不会把 ATL 装进去这是新人翻车的第一站。正确做法打开 Visual Studio Installer点“修改”切到“单个组件”页搜索ATL勾选“适用于最新 v142 生成工具的 C ATL (x86 x64)”然后点修改。装完再启动 VS2019atlbase.h才存在。如果你手头只有 vs2019 离线安装包也同样要走 Installer 里的布局修改流程把 ATL 组件补进本地缓存。网上很多教程让你把 WTL 的 include 目录直接拷进系统 Include 目录我强烈不建议WTL 9 和 10 的头文件结构差异不小全局污染之后换项目就会窜版本。WTL 的 include 就放到你自己指定的目录按工程配路径是最稳的。3. 把 WTL 10.0 配进 VS2019include 路径、最小窗口工程和链接配置3.1 建一个空 C 工程把 WTL 的 include 目录配进去打开 VS2019新建一个“空项目”语言选 C。不用选“Windows 桌面应用程序”模板那个模板默认带了一堆预编译头和框架代码对 WTL 反而是干扰。拿到 WTL 10.0 源码包后解压记住这个路径结构顶层有include、Samples、AppWizard等目录。我们真正需要的是include目录里面是一堆.h头文件没有.cpp。然后打开项目属性配置属性 → VC 目录 → 包含目录把WTL 解压路径\include加进去配置属性 → C/C → 预处理器 → 预处理器定义确认有WIN32、_WINDOWS、_UNICODE、UNICODE配置属性 → 链接器 → 系统 → 子系统选“窗口 (/SUBSYSTEM:WINDOWS)”现在先不写代码有个预处理宏值得顺手配好_WTL_NO_CSTRING。这个宏控制 WTL 是否自动依赖CString。如果你不想让 WTL 强制把 ATL 的CString拉进编译单元可以定义它。但绝大多数项目直接用CString更省事我一般不会定义它而是保留 WTL 默认行为。3.2 最小可运行的窗口程序从 _tWinMain 到消息循环在工程里新建一个main.cpp把下面的代码完整贴进去这是 WTL 10.0 在 VS2019 下能跑通的最小骨架#include atlbase.h #include atlapp.h #include atlwin.h #include atlframe.h // WTL 的全局模块对象很多内部宏会引用它 CAppModule _Module; // 主窗口类继承 CFrameWindowImpl模板参数传自己的类名 class CMainFrame : public CFrameWindowImplCMainFrame { public: // 注册窗口类名 MainFrameWnd不使用菜单 DECLARE_FRAME_WND_CLASS(_T(MainFrameWnd), 0) // 消息映射表声明两个消息分发 BEGIN_MSG_MAP(CMainFrame) MESSAGE_HANDLER(WM_CLOSE, OnClose) MESSAGE_HANDLER(WM_DESTROY, OnDestroy) END_MSG_MAP() // 收到 WM_CLOSE 时销毁窗口 LRESULT OnClose(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { DestroyWindow(); return 0; } // 窗口销毁后向消息循环投递 WM_QUIT LRESULT OnDestroy(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { PostQuitMessage(0); return 0; } }; int WINAPI _tWinMain(HINSTANCE hInstance, HINSTANCE, LPTSTR, int nCmdShow) { // 初始化全局模块第一个参数传 NULL 表示不关联资源模块 _Module.Init(NULL, hInstance); CMainFrame wnd; // 创建窗口标题命名为 WTL 10.0 on VS2019 if (wnd.Create(NULL, CWindow::rcDefault, _T(WTL 10.0 on VS2019)) NULL) { _Module.Term(); return 1; } wnd.ShowWindow(nCmdShow); // 启动消息循环Run 返回 WM_QUIT 携带的退出码 CMessageLoop theLoop; int nRet theLoop.Run(); _Module.Term(); return nRet; }逻辑说明atlapp.h提供CAppModule和CMessageLoopCFrameWindowImpl在atlframe.h中定义它已经包含了窗口注册、创建、消息映射链到基类的默认行为。DECLARE_FRAME_WND_CLASS宏会生成本类自己的窗口类注册代码第一个参数是类名第二个参数是菜单资源 ID。参数说明_Module.Init的第一参数NULL表示资源句柄跟随实例句柄hInstance如果你的资源 DLL 和主程序分开第一个参数要换成资源 DLL 的HINSTANCE。wnd.Create的第二个参数CWindow::rcDefault让系统给窗口一个默认大小第三个参数是窗口标题。CMessageLoop::Run()只有在收到WM_QUIT后才返回返回值可以作为进程退出码。3.3 撞上 LNK2019 / LNK2001入口点、字符集和子系统的三个必查项第一次编译这个工程最常见的错误是链接器提示找不到wWinMain或WinMain。这是因为_tWinMain是一个宏在定义了_UNICODE时被预处理器翻译成wWinMain没定义时翻译成WinMain。VS2019 默认空工程不会替你决定入口点所以你要检查三处链接器 → 系统 → 子系统必须是“窗口”不能是“控制台”链接器 → 高级 → 入口点填wWinMainCRTStartup。如果你觉得自己没定义 Unicode则对应WinMainCRTStartup常规 → 字符集选“使用 Unicode 字符集”保证_UNICODE和UNICODE被定义我个人建议不用管链接器入口点而是直接删掉_tWinMain里的_t写标准签名wWinMain然后显式把字符集设成 Unicode。这样代码和配置一眼就能对上省得宏在中间变来变去。出现LNK2001时先看这两处比乱加 pragma comment 靠谱。提示入口点不等于函数名。你写的wWinMain是用户入口函数链接器去找的启动函数是wWinMainCRTStartup这两者在内部有调用关系配置时不要填错。4. 用 WTL 10.0 写界面消息映射宏、对话框控件读写和属性页4.1 消息映射宏的三种形态MESSAGE_HANDLER、COMMAND_ID_HANDLER、NOTIFY_HANDLERWTL 的界面核心是消息映射宏。一个窗口要处理哪条消息、哪个命令、哪个通知全部写在同一张BEGIN_MSG_MAP/END_MSG_MAP表里。宏展开后编译器会生成一个查找函数按消息 ID 分发表项。写法上有三种用途对应三类消息来源MESSAGE_HANDLER(WM_xxx, Func)处理窗口消息比如WM_CLOSE、WM_SIZE、WM_PAINTCOMMAND_ID_HANDLER(控件ID, Func)处理来自菜单、按钮的WM_COMMANDNOTIFY_HANDLER(控件ID, 通知码, Func)处理WM_NOTIFY比如列表控件LVN_ITEMCHANGED函数签名是统一的LRESULT Func(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled)。注意最后一个参数bHandled如果你想让它继续传给下一张消息映射表就设成FALSE设成TRUE或不改表示本层已经处理完。另外两个高频宏一定要认识CHAIN_MSG_MAP(基类)会把未处理消息链到基类比如你继承CFrameWindowImpl时必须用CHAIN_MSG_MAP(CFrameWindowImpl你的类)才能让默认窗口行为生效。REFLECT_NOTIFICATIONS()用于对话框里的子控件把控件发来的通知反射回控件自身处理适合封装自绘控件时用。4.2 对话框控件的创建与读写从 .rc 资源到 CEdit/CButton 绑定WTL 的对话框不是靠拖控件生成代码而是靠资源编辑器画界面再用CDialogImpl模板类配合控件 ID 做读写。先给一个能编译的.rc片段IDD_MAIN_DLG DIALOGEX 0, 0, 220, 140 STYLE DS_SETFONT | WS_POPUP | WS_CAPTION | WS_SYSMENU CAPTION WTL Dialog FONT 9, Microsoft YaHei BEGIN LTEXT Name:, IDC_STATIC_NAME, 10, 10, 40, 8 EDITTEXT IDC_EDIT_NAME, 55, 10, 100, 14 DEFPUSHBUTTON OK, IDC_BTN_OK, 130, 100, 40, 14 PUSHBUTTON Cancel, IDC_BTN_CANCEL, 175, 100, 40, 14 CONTROL , IDC_LIST1, SysListView32, LVS_REPORT, 10, 30, 205, 60 END对应的对话框类#include atlbase.h #include atlapp.h #include atldlgs.h #include atlctrls.h #include atlmisc.h class CMainDlg : public CDialogImplCMainDlg { public: enum { IDD IDD_MAIN_DLG }; // 关联资源 ID BEGIN_MSG_MAP(CMainDlg) MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog) COMMAND_ID_HANDLER(IDC_BTN_OK, OnBtnOK) COMMAND_ID_HANDLER(IDC_BTN_CANCEL, OnBtnCancel) COMMAND_ID_HANDLER(IDCANCEL, OnCancel) // 处理 Esc 键默认关闭 END_MSG_MAP() // 对话框初始化 LRESULT OnInitDialog(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { // 给编辑框设一个初始文本 SetDlgItemText(IDC_EDIT_NAME, _T(WTL)); // 给列表控件加一列 m_list.Attach(GetDlgItem(IDC_LIST1)); m_list.InsertColumn(0, _T(Item), LVCFMT_LEFT, 180); m_list.InsertItem(0, _T(hello)); return TRUE; // TRUE 让系统不再设置默认焦点 } // 点击 OK 按钮 LRESULT OnBtnOK(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { CString strName; GetDlgItemText(IDC_EDIT_NAME, strName); MessageBox(strName, _T(Input), MB_OK); return 0; } // 点击 Cancel 按钮或按 Esc LRESULT OnBtnCancel(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { EndDialog(IDCANCEL); return 0; } LRESULT OnCancel(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { EndDialog(IDCANCEL); return 0; } CListViewCtrl m_list; // WTL 对 SysListView32 的封装 };逻辑说明CDialogImpl要求你定义enum { IDD 资源ID }这是它定位对话框模板的约定。WM_INITDIALOG是对话框创建后的初始化时机排序必须在其它消息之前。SetDlgItemText、GetDlgItemText是 WTL 继承自CWindow的便捷方法内部自动包装SendMessage。这里我用m_list.Attach(GetDlgItem(IDC_LIST1))把列表控件句柄“附加”到CListViewCtrl封装对象上之后就能调InsertColumn、InsertItem这些看着像 MFC 的接口。参数说明COMMAND_ID_HANDLER的回调四个参数是WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled和裸WM_COMMAND的参数布局一致。IDCANCEL是系统保留的取消命令 ID必须在映射表里单独处理否则按 Esc 对话框不会退出。4.3 多页设置界面从 CPropertyPageImpl 到 CPropertySheetImplWTL 10.0 的属性页机制已经相当成熟写多页设置界面比 MFC 还顺手。每一页继承CPropertyPageImpl整体对话框继承CPropertySheetImpl。先看一页的写法class CSettingsPage1 : public CPropertyPageImplCSettingsPage1 { public: enum { IDD IDD_PAGE1 }; BEGIN_MSG_MAP(CSettingsPage1) COMMAND_ID_HANDLER(IDC_BTN_APPLY, OnApplyClicked) CHAIN_MSG_MAP(CPropertyPageImplCSettingsPage1) END_MSG_MAP() // 点击“应用”按钮时把页面标记为“已修改” LRESULT OnApplyClicked(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { SetModified(); // 这句会让属性页的“应用”按钮亮起来 return 0; } // 用户点击“应用”或“确定”时属性页框架回调这个虚函数 BOOL OnApply() { int nValue GetDlgItemInt(IDC_EDIT_VALUE); // 这里做实际保存 SetDlgItemInt(IDC_STATIC_RESULT, nValue * 2); return TRUE; // 返回 TRUE 表示应用成功 } };属性页容器和调用class CMainSheet : public CPropertySheetImplCMainSheet { public: CMainSheet(LPCTSTR pszTitle, HWND hWndParent NULL) : CPropertySheetImplCMainSheet(pszTitle, hWndParent) { m_page1.Create(GetActivePage() ? GetActivePage()-m_hWnd : NULL); AddPage(m_page1); } CSettingsPage1 m_page1; }; // 在代码里这样打开模态属性页 // CMainSheet sheet(_T(Settings)); // sheet.DoModal();逻辑说明CPropertyPageImpl的OnApply是一个虚函数不是消息处理函数属性页框架会在用户点“应用”时自动调用它。SetModified()的作用是把当前页标记为脏让属性页底部的“应用”按钮从禁用变成可用。你不需要自己显示这个按钮系统属性页框架会处理。参数说明AddPage接受页对象的引用页对象生命周期必须比CMainSheet长所以把m_page1声明为CMainSheet的成员。DoModal()跑完整的模态循环返回值是用户点的结束按钮 ID。5. WTL 10.0 在 VS2019 下的避坑指南从编译错误到界面模糊的五个踩坑记录5.1 打不开 atlbase.hATL 组件缺失和离线安装的顺序现象新建的工程一编译报fatal error C1083: 无法打开包括文件: atlbase.h: No such file or directory。原因VS2019 默认不装 ATL 组件atlbase.h压根不存在于你的 VS 安装目录里。这和 WTL 无关是 VS 自身的组件裁剪问题。解决打开 Visual Studio Installer修改安装在“单个组件”里搜索ATL勾选“适用于最新 v142 生成工具的 C ATL (x86 x64)”安装完成后重启。如果你用的是 vs2019 离线安装包需要在离线布局阶段就把这个组件加进去否则装完还得再拉一次在线流量。5.2 旧版 WTL 在 VS2019 上报 C4430ATL 版本检测失效现象工程里用的是 WTL 9.1 或更早升级到 VS2019 后atlapp.h编译时出现error C4430: 缺少类型说明符或error C2061: 语法错误错误位置在版本宏附近。原因WTL 9.1 内部用_ATL_VER判断 ATL 是否支持某特性VS2019 的 v142 工具集带的 ATL 版本号超出了旧 WTL 的预期值条件编译走进了不存在的分支后面的代码全部错位。这是 9.1 与 VS2019 兼容性差的关键。解决升级到 WTL 10.0 最终版本它的版本检测逻辑是重写过的。临时应付的办法是在包含任何 WTL 头文件之前#define _WTL_NO_ATL_VER跳过检测但不保证所有特性都正常我只把它当诊断手段用不会正式发布。5.3 链接报 LNK2001 _Module全局模块对象没定义或漏了类型现象编译通过链接时报error LNK2001: 无法解析的外部符号 class CAppModule _Module。原因WTL 的atlapp.h内部有一堆宏引用全局变量_Module但你的工程里没有定义这个全局对象或者定义了但拼写、类型不对。这不算 WTL 的 bug而是它约定俗成的全局入口。解决在包含 WTL 头文件的某个.cpp文件顶部加上CAppModule _Module;。注意类型必须是CAppModule不要用CComModule。WTL 10 里CAppModule才是针对线程消息循环优化的类型CComModule是 COM 场景用的。5.4 中文乱码或 C2664字符集不匹配的判定与统一现象运行后界面中文变成问号或者编译时字符串相关函数报C2664: 无法将参数从“wchar_t *”转换为“const char *”。原因工程属性里字符集选了“多字节字符集”但代码里用了_T()宏资源文件里用的是宽字符格式两者在_UNICODE未定义时拧着来。最麻烦的是同一个工程里一部分文件用了L另一部分用了拼起来就是随机乱码。解决全部统一到 Unicode。工程属性 → 配置属性 → 常规 → 字符集 → 使用 Unicode 字符集。代码里字符串只用_T(...)入口函数写成wWinMain文件保存为 UTF-8 with BOM。这样处理之后C2664 基本绝迹乱码也自然消失。5.5 界面在高 DPI 屏幕上发虚WTL 需要自己开 DPI 感知现象在 150% 缩放的笔记本上运行 WTL 程序窗口和文字都是糊的像被强制放大了一倍。原因WTL 10.0 不会自动调用 DPI 感知接口系统把整个窗口当普通位图做缩放拉伸。这是很多老旧 Win32 框架的通病不是 WTL 特例。解决在_Module.Init之前调用 DPI 感知设置。Win10 上推荐SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE)需要Shcore.lib。老系统兼容做法是动态加载这个放到下一章的代码里直接抄。注意DPI 感知设置必须在创建任何窗口之前调用放在_Module.Init前面最保险。运行后再调用不会生效。6. 让 WTL 10.0 项目再稳一点迁移验证的三个检查点和 DPI 修正6.1 从老版本迁到 10.0按这三个顺序验证如果你手里是 WTL 8/9 的项目头文件路径换成 10.0 的 include 之后先别急着跑业务测试。我习惯按三个顺序过第一是编译告警重点看GetWindowLongPtr、reinterpret_cast相关的行WTL 10 修了 64 位隐患老代码里常见的LONG到指针转换在这里会暴露第二是消息反射对话框里如果有自绘控件跑一遍打开、关闭、切换页确认REFLECT_NOTIFICATIONS()行为没变WTL 10 对通知反射的触发时机有调整第三是资源把.rc里DIALOGEX和控件定义的写法跟 SDK 头文件对齐老工程里过时的控件样式BS_ICON之类的在新头文件下可能失效。6.2 DPI 感知的代码级修正入口处加三行最能立竿见影的技巧就是把这个函数贴到_Module.Init之前#include shellscalingapi.h #pragma comment(lib, Shcore.lib) // 在 _Module.Init(NULL, hInstance) 之前调用 if (SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE) ! S_OK) { // 老系统上可能失败回退到系统级感知 SetProcessDPIAware(); }逻辑说明PROCESS_PER_MONITOR_DPI_AWARE让系统按每个显示器实际缩放比渲染窗口多显示器接不同缩放时窗口不会糊。SetProcessDPIAware是老一代接口只在系统级生效双屏切换时可能仍会有轻微缩放属于保底方案。参数说明SetProcessDpiAwareness的枚举值是PROCESS_DPI_UNAWARE、PROCESS_SYSTEM_DPI_AWARE、PROCESS_PER_MONITOR_DPI_AWARE三个选最后一个即可。如果程序将来要切到 VS2022这个调用不变WTL 10.0 在 VS2022 上同样适用。做完这些窗口在高 DPI 下清晰了老项目迁移也能安全落地。我现在的习惯是每接一个老 WTL 项目先按 6.1 的顺序做一遍体检再改 DPI最后才动业务代码。这个顺序帮我挡掉了不少上线后的模糊、崩溃类返工希望帮到你。本文还有配套的精品资源点击获取
简介WTL10.0是微软轻量级C库的最终版本专门针对Visual Studio 2019做了适配与优化面向希望直接调用Windows API、构建高效小巧桌面程序的C开发者。压缩包共收纳296个文件整体约704KB其中104个头文件与39个C源文件构成核心库另有sln、vcxproj等多套示例工程bmp、ico、rc等界面资源以及html、txt、hhc等文档索引方便在VS2019中安装、编译和查阅。目前已有325人学习下载。包内附带了安装向导、示例代码、完整的头文件与库文件、更新日志和API参考文档开发者可据此快速搭好WTL开发环境借助模板类、消息映射和Unicode支持编写出结构清晰、便于维护的Windows程序同时它保留了对ATL、MFC乃至Boost的良好兼容性适合具备C基础、希望在轻量框架下替代MFC的中高级开发者。1. WTL 10.0 最终版本为什么 VS2019 用户还在翻它的牌2019 年 10.0 最终版本发布之后WTL 进入了长期维护模式但这恰恰是它适合当下的原因API 不再大幅变动坑基本被人踩平了。对还在 VS2019 上维护内网工具、设备上位机程序、插件面板的 C 工程师来说WTL 10.0 是一个介于 MFC 和裸 Win32 之间的舒服位置——不需要分发运行库一个 exe 几百 KB编译快界面编写又比手写 Win32 消息循环省一半力气。这篇文章直接以 VS2019 为环境把 WTL 10.0 的依赖链、工程配置、消息映射、对话框和常见编译坑一次讲透。2. 从 ATL 到 WTL 10.0搞懂依赖链避开 VS2019 的 ATL 版本坑2.1 WTL 不是又一个 UI 库它是 ATL 的“民间官方扩展”先把这个关系说清楚不然配环境时你会一脸茫然。ATLActive Template Library是微软做 COM 组件用的轻量模板库本身不提供窗口框架。WTL 的全称是 Windows Template Library它做的事情就是把 ATL 的模板思路延伸到窗口上以CWindow为根让窗口类、对话框类、控件封装全部变成模板类和宏的组合。跟 MFC 比WTL 最大的不同在于没有运行时依赖。MFC 程序不管动态还是静态链接编译产物里都带着一整套类库的痕迹升级 VS 版本时经常要跟着改。WTL 程序编译时只依赖 ATL 头文件和系统库运行时不需要分发任何 WTL 动态库发布一个 exe 就完事。这对我来说是最有吸引力的一点内网机器上往往缺少各种 VC 运行库而 WTL 程序双击就跑。下面是三个方案在实践中的对比你判断自己该不该转对比项MFCWTL裸 Win32运行时依赖MFC DLL 或静态运行库仅系统 DLL无界面代码量少向导强较少宏简洁多全手写产物体积大小最小但代码量失控控件封装全面够用无消息处理消息表 向导消息映射宏手工 switch学习曲线中中高高我早期做过一个监控小工具MFC 版本发布后要带 3 个 DLL换到 WTL 后变成一个 400 KB 的单 exe客户拷贝直接跑。就这一条足够让老项目翻牌子。2.2 为什么说 10.0 是“最终版本”VS2019 兼容性之外的事实清单WTL 的版本线从 7.x 走到 8.x、9.x到 10.0 时官方明确把适配重点放到了 VS2019 上。当时的核心问题不是 WTL 代码本身而是 ATL 的版本检测。WTL 头文件里大量代码靠_ATL_VER这个宏判断当前 ATL 支持哪些特性VS2019 的 v142 工具集带的 ATL 版本号比 WTL 9.1 预期的高导致条件编译走错分支出现一批莫名其妙的编译错误。10.0 做了三件关键事一是重写了 ATL 版本检测逻辑让 v142 工具集能正常通过二是修了一批 64 位编译告警老代码里GetWindowLong转GetWindowLongPtr的隐患被处理三是对 Windows 10 SDK 新增的头文件和控件做了适配。之后项目进入修复式维护没有继续规划 11所以“最终版本”这个说法是准确的。这里有个容易被忽略的点WTL 10.0 的代码风格还是老式的 C98/03 那一套编译不需要开 C11/C14。你在 VS2019 里用默认标准编译完全没问题反而别随手开/std:clatest去追新标准开了之后某些第三方库的告警会盖住你自己的问题。2.3 VS2019 必须先装 ATL 组件否则头文件都打不开WTL 头文件的第一行几乎都带着#include atlbase.h而这个atlbase.h不在 Windows SDK 里属于 VS 的 ATL 组件。VS2019 安装时默认“使用 C 的桌面开发”工作负载并不会把 ATL 装进去这是新人翻车的第一站。正确做法打开 Visual Studio Installer点“修改”切到“单个组件”页搜索ATL勾选“适用于最新 v142 生成工具的 C ATL (x86 x64)”然后点修改。装完再启动 VS2019atlbase.h才存在。如果你手头只有 vs2019 离线安装包也同样要走 Installer 里的布局修改流程把 ATL 组件补进本地缓存。网上很多教程让你把 WTL 的 include 目录直接拷进系统 Include 目录我强烈不建议WTL 9 和 10 的头文件结构差异不小全局污染之后换项目就会窜版本。WTL 的 include 就放到你自己指定的目录按工程配路径是最稳的。3. 把 WTL 10.0 配进 VS2019include 路径、最小窗口工程和链接配置3.1 建一个空 C 工程把 WTL 的 include 目录配进去打开 VS2019新建一个“空项目”语言选 C。不用选“Windows 桌面应用程序”模板那个模板默认带了一堆预编译头和框架代码对 WTL 反而是干扰。拿到 WTL 10.0 源码包后解压记住这个路径结构顶层有include、Samples、AppWizard等目录。我们真正需要的是include目录里面是一堆.h头文件没有.cpp。然后打开项目属性配置属性 → VC 目录 → 包含目录把WTL 解压路径\include加进去配置属性 → C/C → 预处理器 → 预处理器定义确认有WIN32、_WINDOWS、_UNICODE、UNICODE配置属性 → 链接器 → 系统 → 子系统选“窗口 (/SUBSYSTEM:WINDOWS)”现在先不写代码有个预处理宏值得顺手配好_WTL_NO_CSTRING。这个宏控制 WTL 是否自动依赖CString。如果你不想让 WTL 强制把 ATL 的CString拉进编译单元可以定义它。但绝大多数项目直接用CString更省事我一般不会定义它而是保留 WTL 默认行为。3.2 最小可运行的窗口程序从 _tWinMain 到消息循环在工程里新建一个main.cpp把下面的代码完整贴进去这是 WTL 10.0 在 VS2019 下能跑通的最小骨架#include atlbase.h #include atlapp.h #include atlwin.h #include atlframe.h // WTL 的全局模块对象很多内部宏会引用它 CAppModule _Module; // 主窗口类继承 CFrameWindowImpl模板参数传自己的类名 class CMainFrame : public CFrameWindowImplCMainFrame { public: // 注册窗口类名 MainFrameWnd不使用菜单 DECLARE_FRAME_WND_CLASS(_T(MainFrameWnd), 0) // 消息映射表声明两个消息分发 BEGIN_MSG_MAP(CMainFrame) MESSAGE_HANDLER(WM_CLOSE, OnClose) MESSAGE_HANDLER(WM_DESTROY, OnDestroy) END_MSG_MAP() // 收到 WM_CLOSE 时销毁窗口 LRESULT OnClose(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { DestroyWindow(); return 0; } // 窗口销毁后向消息循环投递 WM_QUIT LRESULT OnDestroy(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { PostQuitMessage(0); return 0; } }; int WINAPI _tWinMain(HINSTANCE hInstance, HINSTANCE, LPTSTR, int nCmdShow) { // 初始化全局模块第一个参数传 NULL 表示不关联资源模块 _Module.Init(NULL, hInstance); CMainFrame wnd; // 创建窗口标题命名为 WTL 10.0 on VS2019 if (wnd.Create(NULL, CWindow::rcDefault, _T(WTL 10.0 on VS2019)) NULL) { _Module.Term(); return 1; } wnd.ShowWindow(nCmdShow); // 启动消息循环Run 返回 WM_QUIT 携带的退出码 CMessageLoop theLoop; int nRet theLoop.Run(); _Module.Term(); return nRet; }逻辑说明atlapp.h提供CAppModule和CMessageLoopCFrameWindowImpl在atlframe.h中定义它已经包含了窗口注册、创建、消息映射链到基类的默认行为。DECLARE_FRAME_WND_CLASS宏会生成本类自己的窗口类注册代码第一个参数是类名第二个参数是菜单资源 ID。参数说明_Module.Init的第一参数NULL表示资源句柄跟随实例句柄hInstance如果你的资源 DLL 和主程序分开第一个参数要换成资源 DLL 的HINSTANCE。wnd.Create的第二个参数CWindow::rcDefault让系统给窗口一个默认大小第三个参数是窗口标题。CMessageLoop::Run()只有在收到WM_QUIT后才返回返回值可以作为进程退出码。3.3 撞上 LNK2019 / LNK2001入口点、字符集和子系统的三个必查项第一次编译这个工程最常见的错误是链接器提示找不到wWinMain或WinMain。这是因为_tWinMain是一个宏在定义了_UNICODE时被预处理器翻译成wWinMain没定义时翻译成WinMain。VS2019 默认空工程不会替你决定入口点所以你要检查三处链接器 → 系统 → 子系统必须是“窗口”不能是“控制台”链接器 → 高级 → 入口点填wWinMainCRTStartup。如果你觉得自己没定义 Unicode则对应WinMainCRTStartup常规 → 字符集选“使用 Unicode 字符集”保证_UNICODE和UNICODE被定义我个人建议不用管链接器入口点而是直接删掉_tWinMain里的_t写标准签名wWinMain然后显式把字符集设成 Unicode。这样代码和配置一眼就能对上省得宏在中间变来变去。出现LNK2001时先看这两处比乱加 pragma comment 靠谱。提示入口点不等于函数名。你写的wWinMain是用户入口函数链接器去找的启动函数是wWinMainCRTStartup这两者在内部有调用关系配置时不要填错。4. 用 WTL 10.0 写界面消息映射宏、对话框控件读写和属性页4.1 消息映射宏的三种形态MESSAGE_HANDLER、COMMAND_ID_HANDLER、NOTIFY_HANDLERWTL 的界面核心是消息映射宏。一个窗口要处理哪条消息、哪个命令、哪个通知全部写在同一张BEGIN_MSG_MAP/END_MSG_MAP表里。宏展开后编译器会生成一个查找函数按消息 ID 分发表项。写法上有三种用途对应三类消息来源MESSAGE_HANDLER(WM_xxx, Func)处理窗口消息比如WM_CLOSE、WM_SIZE、WM_PAINTCOMMAND_ID_HANDLER(控件ID, Func)处理来自菜单、按钮的WM_COMMANDNOTIFY_HANDLER(控件ID, 通知码, Func)处理WM_NOTIFY比如列表控件LVN_ITEMCHANGED函数签名是统一的LRESULT Func(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled)。注意最后一个参数bHandled如果你想让它继续传给下一张消息映射表就设成FALSE设成TRUE或不改表示本层已经处理完。另外两个高频宏一定要认识CHAIN_MSG_MAP(基类)会把未处理消息链到基类比如你继承CFrameWindowImpl时必须用CHAIN_MSG_MAP(CFrameWindowImpl你的类)才能让默认窗口行为生效。REFLECT_NOTIFICATIONS()用于对话框里的子控件把控件发来的通知反射回控件自身处理适合封装自绘控件时用。4.2 对话框控件的创建与读写从 .rc 资源到 CEdit/CButton 绑定WTL 的对话框不是靠拖控件生成代码而是靠资源编辑器画界面再用CDialogImpl模板类配合控件 ID 做读写。先给一个能编译的.rc片段IDD_MAIN_DLG DIALOGEX 0, 0, 220, 140 STYLE DS_SETFONT | WS_POPUP | WS_CAPTION | WS_SYSMENU CAPTION WTL Dialog FONT 9, Microsoft YaHei BEGIN LTEXT Name:, IDC_STATIC_NAME, 10, 10, 40, 8 EDITTEXT IDC_EDIT_NAME, 55, 10, 100, 14 DEFPUSHBUTTON OK, IDC_BTN_OK, 130, 100, 40, 14 PUSHBUTTON Cancel, IDC_BTN_CANCEL, 175, 100, 40, 14 CONTROL , IDC_LIST1, SysListView32, LVS_REPORT, 10, 30, 205, 60 END对应的对话框类#include atlbase.h #include atlapp.h #include atldlgs.h #include atlctrls.h #include atlmisc.h class CMainDlg : public CDialogImplCMainDlg { public: enum { IDD IDD_MAIN_DLG }; // 关联资源 ID BEGIN_MSG_MAP(CMainDlg) MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog) COMMAND_ID_HANDLER(IDC_BTN_OK, OnBtnOK) COMMAND_ID_HANDLER(IDC_BTN_CANCEL, OnBtnCancel) COMMAND_ID_HANDLER(IDCANCEL, OnCancel) // 处理 Esc 键默认关闭 END_MSG_MAP() // 对话框初始化 LRESULT OnInitDialog(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL bHandled) { // 给编辑框设一个初始文本 SetDlgItemText(IDC_EDIT_NAME, _T(WTL)); // 给列表控件加一列 m_list.Attach(GetDlgItem(IDC_LIST1)); m_list.InsertColumn(0, _T(Item), LVCFMT_LEFT, 180); m_list.InsertItem(0, _T(hello)); return TRUE; // TRUE 让系统不再设置默认焦点 } // 点击 OK 按钮 LRESULT OnBtnOK(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { CString strName; GetDlgItemText(IDC_EDIT_NAME, strName); MessageBox(strName, _T(Input), MB_OK); return 0; } // 点击 Cancel 按钮或按 Esc LRESULT OnBtnCancel(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { EndDialog(IDCANCEL); return 0; } LRESULT OnCancel(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { EndDialog(IDCANCEL); return 0; } CListViewCtrl m_list; // WTL 对 SysListView32 的封装 };逻辑说明CDialogImpl要求你定义enum { IDD 资源ID }这是它定位对话框模板的约定。WM_INITDIALOG是对话框创建后的初始化时机排序必须在其它消息之前。SetDlgItemText、GetDlgItemText是 WTL 继承自CWindow的便捷方法内部自动包装SendMessage。这里我用m_list.Attach(GetDlgItem(IDC_LIST1))把列表控件句柄“附加”到CListViewCtrl封装对象上之后就能调InsertColumn、InsertItem这些看着像 MFC 的接口。参数说明COMMAND_ID_HANDLER的回调四个参数是WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled和裸WM_COMMAND的参数布局一致。IDCANCEL是系统保留的取消命令 ID必须在映射表里单独处理否则按 Esc 对话框不会退出。4.3 多页设置界面从 CPropertyPageImpl 到 CPropertySheetImplWTL 10.0 的属性页机制已经相当成熟写多页设置界面比 MFC 还顺手。每一页继承CPropertyPageImpl整体对话框继承CPropertySheetImpl。先看一页的写法class CSettingsPage1 : public CPropertyPageImplCSettingsPage1 { public: enum { IDD IDD_PAGE1 }; BEGIN_MSG_MAP(CSettingsPage1) COMMAND_ID_HANDLER(IDC_BTN_APPLY, OnApplyClicked) CHAIN_MSG_MAP(CPropertyPageImplCSettingsPage1) END_MSG_MAP() // 点击“应用”按钮时把页面标记为“已修改” LRESULT OnApplyClicked(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL bHandled) { SetModified(); // 这句会让属性页的“应用”按钮亮起来 return 0; } // 用户点击“应用”或“确定”时属性页框架回调这个虚函数 BOOL OnApply() { int nValue GetDlgItemInt(IDC_EDIT_VALUE); // 这里做实际保存 SetDlgItemInt(IDC_STATIC_RESULT, nValue * 2); return TRUE; // 返回 TRUE 表示应用成功 } };属性页容器和调用class CMainSheet : public CPropertySheetImplCMainSheet { public: CMainSheet(LPCTSTR pszTitle, HWND hWndParent NULL) : CPropertySheetImplCMainSheet(pszTitle, hWndParent) { m_page1.Create(GetActivePage() ? GetActivePage()-m_hWnd : NULL); AddPage(m_page1); } CSettingsPage1 m_page1; }; // 在代码里这样打开模态属性页 // CMainSheet sheet(_T(Settings)); // sheet.DoModal();逻辑说明CPropertyPageImpl的OnApply是一个虚函数不是消息处理函数属性页框架会在用户点“应用”时自动调用它。SetModified()的作用是把当前页标记为脏让属性页底部的“应用”按钮从禁用变成可用。你不需要自己显示这个按钮系统属性页框架会处理。参数说明AddPage接受页对象的引用页对象生命周期必须比CMainSheet长所以把m_page1声明为CMainSheet的成员。DoModal()跑完整的模态循环返回值是用户点的结束按钮 ID。5. WTL 10.0 在 VS2019 下的避坑指南从编译错误到界面模糊的五个踩坑记录5.1 打不开 atlbase.hATL 组件缺失和离线安装的顺序现象新建的工程一编译报fatal error C1083: 无法打开包括文件: atlbase.h: No such file or directory。原因VS2019 默认不装 ATL 组件atlbase.h压根不存在于你的 VS 安装目录里。这和 WTL 无关是 VS 自身的组件裁剪问题。解决打开 Visual Studio Installer修改安装在“单个组件”里搜索ATL勾选“适用于最新 v142 生成工具的 C ATL (x86 x64)”安装完成后重启。如果你用的是 vs2019 离线安装包需要在离线布局阶段就把这个组件加进去否则装完还得再拉一次在线流量。5.2 旧版 WTL 在 VS2019 上报 C4430ATL 版本检测失效现象工程里用的是 WTL 9.1 或更早升级到 VS2019 后atlapp.h编译时出现error C4430: 缺少类型说明符或error C2061: 语法错误错误位置在版本宏附近。原因WTL 9.1 内部用_ATL_VER判断 ATL 是否支持某特性VS2019 的 v142 工具集带的 ATL 版本号超出了旧 WTL 的预期值条件编译走进了不存在的分支后面的代码全部错位。这是 9.1 与 VS2019 兼容性差的关键。解决升级到 WTL 10.0 最终版本它的版本检测逻辑是重写过的。临时应付的办法是在包含任何 WTL 头文件之前#define _WTL_NO_ATL_VER跳过检测但不保证所有特性都正常我只把它当诊断手段用不会正式发布。5.3 链接报 LNK2001 _Module全局模块对象没定义或漏了类型现象编译通过链接时报error LNK2001: 无法解析的外部符号 class CAppModule _Module。原因WTL 的atlapp.h内部有一堆宏引用全局变量_Module但你的工程里没有定义这个全局对象或者定义了但拼写、类型不对。这不算 WTL 的 bug而是它约定俗成的全局入口。解决在包含 WTL 头文件的某个.cpp文件顶部加上CAppModule _Module;。注意类型必须是CAppModule不要用CComModule。WTL 10 里CAppModule才是针对线程消息循环优化的类型CComModule是 COM 场景用的。5.4 中文乱码或 C2664字符集不匹配的判定与统一现象运行后界面中文变成问号或者编译时字符串相关函数报C2664: 无法将参数从“wchar_t *”转换为“const char *”。原因工程属性里字符集选了“多字节字符集”但代码里用了_T()宏资源文件里用的是宽字符格式两者在_UNICODE未定义时拧着来。最麻烦的是同一个工程里一部分文件用了L另一部分用了拼起来就是随机乱码。解决全部统一到 Unicode。工程属性 → 配置属性 → 常规 → 字符集 → 使用 Unicode 字符集。代码里字符串只用_T(...)入口函数写成wWinMain文件保存为 UTF-8 with BOM。这样处理之后C2664 基本绝迹乱码也自然消失。5.5 界面在高 DPI 屏幕上发虚WTL 需要自己开 DPI 感知现象在 150% 缩放的笔记本上运行 WTL 程序窗口和文字都是糊的像被强制放大了一倍。原因WTL 10.0 不会自动调用 DPI 感知接口系统把整个窗口当普通位图做缩放拉伸。这是很多老旧 Win32 框架的通病不是 WTL 特例。解决在_Module.Init之前调用 DPI 感知设置。Win10 上推荐SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE)需要Shcore.lib。老系统兼容做法是动态加载这个放到下一章的代码里直接抄。注意DPI 感知设置必须在创建任何窗口之前调用放在_Module.Init前面最保险。运行后再调用不会生效。6. 让 WTL 10.0 项目再稳一点迁移验证的三个检查点和 DPI 修正6.1 从老版本迁到 10.0按这三个顺序验证如果你手里是 WTL 8/9 的项目头文件路径换成 10.0 的 include 之后先别急着跑业务测试。我习惯按三个顺序过第一是编译告警重点看GetWindowLongPtr、reinterpret_cast相关的行WTL 10 修了 64 位隐患老代码里常见的LONG到指针转换在这里会暴露第二是消息反射对话框里如果有自绘控件跑一遍打开、关闭、切换页确认REFLECT_NOTIFICATIONS()行为没变WTL 10 对通知反射的触发时机有调整第三是资源把.rc里DIALOGEX和控件定义的写法跟 SDK 头文件对齐老工程里过时的控件样式BS_ICON之类的在新头文件下可能失效。6.2 DPI 感知的代码级修正入口处加三行最能立竿见影的技巧就是把这个函数贴到_Module.Init之前#include shellscalingapi.h #pragma comment(lib, Shcore.lib) // 在 _Module.Init(NULL, hInstance) 之前调用 if (SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE) ! S_OK) { // 老系统上可能失败回退到系统级感知 SetProcessDPIAware(); }逻辑说明PROCESS_PER_MONITOR_DPI_AWARE让系统按每个显示器实际缩放比渲染窗口多显示器接不同缩放时窗口不会糊。SetProcessDPIAware是老一代接口只在系统级生效双屏切换时可能仍会有轻微缩放属于保底方案。参数说明SetProcessDpiAwareness的枚举值是PROCESS_DPI_UNAWARE、PROCESS_SYSTEM_DPI_AWARE、PROCESS_PER_MONITOR_DPI_AWARE三个选最后一个即可。如果程序将来要切到 VS2022这个调用不变WTL 10.0 在 VS2022 上同样适用。做完这些窗口在高 DPI 下清晰了老项目迁移也能安全落地。我现在的习惯是每接一个老 WTL 项目先按 6.1 的顺序做一遍体检再改 DPI最后才动业务代码。这个顺序帮我挡掉了不少上线后的模糊、崩溃类返工希望帮到你。本文还有配套的精品资源点击获取
