如果你刚从 Win32 转过来写 C/WinRT第一件需要适应的就是“文件不再是一个句柄”。过去我打开文件拿到 HFILE然后 ReadFile、WriteFile一套组合拳打完收工。到了 C/WinRT 里文件被封装成了StorageFile对象读文件不再是一个同步函数而是一个返回IAsyncOperationT的异步操作——你不能立刻拿到内容要么co_await等它完成要么挂回调。这篇教程作为系列的第二篇专门聊文件处理怎么拿到文件对象、怎么读文本、怎么写二进制、怎么流式处理大文件以及我实际踩过的那些坑。适合刚搭好 C/WinRT 开发环境、准备写文件读写逻辑的朋友不管你做的是桌面工具还是 WinUI 应用这份内容应该都能帮上忙。1. 绕不开的第一课文件处理的思维切换1.1 Win32 那套经验为什么在这里不灵先说说为什么很多人初学 C/WinRT 文件处理会难受。Win32 时代你打开文件是命令式的CreateFile返回一个内核句柄接下来ReadFile、WriteFile、CloseHandle每一步都是同步阻塞的文件不存在就返回INVALID_HANDLE_VALUE再用GetLastError查原因。这套模型很直接但它把文件访问的细节、句柄生命周期、共享模式全丢给开发者。C/WinRT 里的设计完全不同。文件对应的是Windows::Storage::StorageFile对象这个对象代表一个文件条目但它不是句柄——它更像一把“钥匙”你拿它去申请各种异步操作比如读取、写入、获取属性。API 层面对你屏蔽了底层句柄同时引入了权限模型你能访问哪些文件不取决于你的进程身份而取决于应用声明的能力和用户授权。这也是为什么你在 Win32 里能C:\Anything随便读在 WinRT 模型里却经常遇到“访问被拒绝”。这不是倒退而是 Windows 应用模型整体向沙盒化演进的结果。哪怕你现在写的是非打包的桌面应用、权限监管相对宽松我也建议你一开始就按这个约束去设计代码——后面万一要打包分发、上架商店或者把逻辑迁移到其他 WinRT 项目里就不会被权限问题打一个措手不及。另一个明显的差异是异步。WinRT 的 I/O 接口几乎全是异步的原因很简单UI 线程不能阻塞。如果你在 Win32 里读一个几百 MB 的文件界面会卡住这是老应用常见的卡顿来源。WinRT 把“读取文件”变成一个异步任务配合 C/WinRT 的协程支持写起来跟同步代码差不多但底层不会阻塞线程。1.2 认识 StorageFile 和它的异步家族StorageFile是文件处理的入口对象它有几个常用属性Name()文件名比如report.txtPath()完整路径注意打包应用里路径可能形如C:\Users\...\AppData\Local\Packages\...FileType()扩展名带点号如.txtAttributes()文件属性标志这些属性的返回类型大多是winrt::hstring也就是 WinRT 的字符串类型。后面读写文件时凡是看到hstring都建议直接当作 UTF-16 字符串对待和std::wstring的互转很自然。围绕StorageFile的异步操作通常长这样IAsyncOperationStorageFile // 获取文件 IAsyncOperationhstring // 读取文本 IAsyncOperationIBuffer // 读取二进制 IAsyncAction // 写入无返回值IAsyncOperationT可以看作一个“未来的值”的包装。在 C/WinRT 里最常用的消费方式就是co_awaitStorageFile file co_await GetFileAsync(); winrt::hstring text co_await FileIO::ReadTextAsync(file);这样写出来的代码接近同步代码的阅读体验但执行是异步的。理解这一点后面所有文件操作就都好办了。2. 开工前先把环境对齐2.1 项目配置与依赖C/WinRT 不是一个单独的库而是一套语言投影和工具链。现在大多数开发环境里新建项目时勾选“C/WinRT”支持即可它会自动配置好头文件生成、元数据投影和构建工具。老项目或者从零手搓的话可以通过包管理器安装官方提供的 C/WinRT 工具链包这是最省事的方式。关键配置项我整理了一张表你在项目属性里对照检查就行配置项推荐值说明语言标准/std:c17或更高C/WinRT 依赖协程C17 起步Windows 运行时语言扩展/ZW启用 WinRT 语言投影字符集Unicode文件路径和处理基本以 UTF-16 为主C/WinRT 工具链随环境更新到最新老版本对部分 API 的投影不完整如果你是用命令行或者 CMake 构建核心就是两个点第一编译器要开启 C17 和 WinRT 扩展第二要确保winrt头文件目录在 include 路径里。官方文档对 CMake 的配置有现成示例照着抄就行这里不重复。2.2 头文件和命名空间文件处理涉及三个主要的 WinRT 命名空间头文件得引全#include winrt/Windows.Foundation.h #include winrt/Windows.Storage.h #include winrt/Windows.Storage.Pickers.h #include winrt/Windows.Storage.Streams.h #include winrt/Windows.Foundation.Collections.h对应的using指令using namespace winrt; using namespace Windows::Foundation; using namespace Windows::Storage; using namespace Windows::Storage::Pickers; using namespace Windows::Storage::Streams;这三个命名空间的职责大概是Windows::Storage核心文件对象StorageFile、StorageFolder、FileIO、KnownFolders都在这里Windows::Storage::Pickers文件选择器用于让用户交互式选择文件Windows::Storage::Streams流和缓冲区比如DataReader、DataWriter、IBufferWindows::Foundation基础类型IAsyncOperation、Uri都在这里漏掉Streams头文件是新人最常见的问题读文本可能还用不到但一碰二进制就立刻报错。2.3 别忘了初始化 Apartment如果你是写 Win32 桌面程序或者控制台程序入口处一定要调用winrt::init_apartment();这行代码负责初始化 COM 和 WinRT 运行时。默认情况下它会根据当前线程类型尝试创建单线程套间STA。对于带 UI 的应用这基本是必须的因为很多 WinRT 异步操作和 UI 控件要求 STA 线程。控制台应用里如果遇到激活失败也可以显式指定winrt::init_apartment(winrt::apartment_type::single_threaded);忘了调用init_apartment的典型症状是某些 API 调用在 debug 构建下直接断言失败或者抛出一个 “CoInitialize has not been called” 之类的异常排查起来还挺迷惑。3. 获取文件对象的四种途径在 C/WinRT 里写文件之前先得拿到StorageFile。获取途径根据场景不同有四种常见方式下面逐一拆解。3.1 交给用户选择FileOpenPicker这是最通用、权限上最省心的方式。用户自己通过系统选择器挑文件应用获得的是用户明确授权的文件几乎不会碰到权限问题。FileOpenPicker picker; picker.FileTypeFilter().Append(L.txt); picker.FileTypeFilter().Append(L.log); picker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary); StorageFile file co_await picker.PickSingleFileAsync(); if (file nullptr) { // 用户取消了选择取消失败不抛异常 co_return; }这里有两个细节容易出错。第一FileTypeFilter()至少要添加一个扩展名否则PickSingleFileAsync会直接抛异常。扩展名必须带点比如L.txtLtxt是无效的。第二如果用户点了取消返回值是空指针不是异常。这个分支必须处理否则后面读写会崩溃。我见过不少朋友在这里直接往下走结果空指针访问抛出一堆让人摸不着头脑的错误。3.2 知道完整路径直接用GetFileFromPathAsync如果已经知道文件的完整路径可以直接用静态方法获取StorageFile file co_await StorageFile::GetFileFromPathAsync(LC:\\Data\\report.txt);这个方法很方便但有两个前提路径必须存在应用必须对该路径有访问权限。在权限收紧的沙盒模型下如果你试图访问未声明能力的位置这里就会抛出异常。捕获异常的姿势我建议从一开始就养成习惯try { StorageFile file co_await StorageFile::GetFileFromPathAsync(path); } catch (winrt::hresult_error const ex) { // 打印错误码和描述 std::wstring msg ex.message().c_str(); HRESULT hr ex.to_hr(); }hresult_error是 C/WinRT 异步操作抛异常时最常见的类型to_hr()返回 HRESULT 错误码message()返回可读描述。后面排查问题全靠它。3.3 按文件夹查找KnownFolders 与 StorageFolder还有一种常见场景是“我知道文件在一个特殊的文件夹里”比如文档库、图片库、下载目录。这时候可以用KnownFoldersStorageFolder folder co_await KnownFolders::GetFolderForUserAsync( nullptr, KnownFolderId::DocumentsLibrary); StorageFile file co_await folder.GetFileAsync(Lreport.txt);如果你想枚举文件夹下所有文件auto files co_await folder.GetFilesAsync(); for (auto const item : files) { // item 是 StorageFile }使用KnownFolders的代价是如果访问的是受保护的库比如文档库、图片库需要在应用清单里声明对应的能力。而且这类能力不是普通声明就能过的商店审核会要求你说明用途。个人项目自己调试时可以打开但真要发布就得慎重。3.4 读取应用内资源ApplicationUri如果只是想读取随程序发布的配置文件、图片、文本资源最优雅的方式是通过ms-appx协议Uri uri(Lms-appx:///Assets/config.json); StorageFile file co_await StorageFile::GetFileFromApplicationUriAsync(uri);注意ms-appx:///后面跟的是应用包内的相对路径。这种方式完全不需要权限声明是读取只读资源的标准姿势。对应地ms-appdata:///local/可以访问应用本地数据目录适合存放运行时生成的数据文件。这四种方式没有绝对的好坏核心是匹配场景。用户交互选文件用 Picker已知路径用GetFileFromPathAsync库文件夹遍历用KnownFolders程序自带资源用ApplicationUri。我实际工作中的经验是能走 Picker 就别走裸路径权限坑少一半。4. 读写文件的完整实操4.1 文本读写的三种姿势拿StorageFile之后最常用的是FileIO静态类。读文本StorageFile file co_await picker.PickSingleFileAsync(); if (file nullptr) co_return; winrt::hstring contents co_await FileIO::ReadTextAsync(file); // 转成 std::wstring 后按需处理 std::wstring text contents;写文本co_await FileIO::WriteTextAsync(file, Lhello cppwinrt);WriteTextAsync会覆盖整个文件。如果你只想把内容追加到末尾用AppendTextAsyncco_await FileIO::AppendTextAsync(file, L\n下一行日志);这三个方法覆盖了 80% 的文本文件需求。还有一个容易被忽略的点ReadTextAsync的默认编码是 UTF-8。如果你的文件是带 BOM 的 UTF-16或者系统 ANSI 编码它也能正确解读吗实测下来带 BOM 的 UTF-16 能识别出来但纯 ANSI 无 BOM 的文件就可能乱码。遇到这种情况用指定编码的重载winrt::hstring contents co_await FileIO::ReadTextAsync(file, UnicodeEncoding::Utf8);UnicodeEncoding枚举在Windows::Storage里有Utf8、Utf16LE、Utf16BE。总之文本编码这件事越早明确越好否则“在某些机器上中文乱码”这种问题能折磨你好几天。4.2 追加写入与流定位上面说了AppendTextAsync但还有一种更底层的追加方式适合需要精细控制写入位置的场景。核心是先打开文件的读写流把流位置挪到末尾再用DataWriter写auto stream co_await file.OpenAsync(FileAccessMode::ReadWrite); stream.Seek(stream.Size()); // 移到文件末尾 auto writer DataWriter(stream.GetOutputStreamAt(0)); writer.WriteString(L追加的内容); co_await writer.StoreAsync();OpenAsync(FileAccessMode::ReadWrite)返回一个支持随机访问的流对象Seek用来定位到指定偏移量。这里有个细节GetOutputStreamAt(0)返回的是从当前文件位置开始写但如果你已经Seek过了这个位置是相对文件开头的所以先Seek(stream.Size())再拿输出流才能确保追加在末尾。用DataWriter写完要调StoreAsync()这是把缓冲区数据真正提交到文件的动作。忘记调StoreAsync是最常见的静默失败原因——代码不报错文件也不变。4.3 二进制与缓冲区操作二进制读写和文本套路不太一样。读二进制auto buffer co_await FileIO::ReadBufferAsync(file); auto reader DataReader::FromBuffer(buffer); // 读取全部字节 uint32_t length reader.UnconsumedBufferLength(); std::vectoruint8_t bytes(length); reader.ReadBytes(bytes);写二进制auto writer DataWriter(); writer.WriteBytes(bytes); // std::vectoruint8_t co_await FileIO::WriteBufferAsync(file, writer.DetachBuffer());这几个环节各自有坑。第一DataReader::FromBuffer(buffer)创建的读取器是“一次性”的它从缓冲区开头开始读读走的数据不会回到缓冲区但你没法换个位置重读。如果需要随机访问得用流的GetInputStreamAt方式而不是简单包一层FromBuffer。第二writer.DetachBuffer()会把DataWriter内部累积的缓冲区“抽走”交给WriteBufferAsync。DetachBuffer之后writer就不能再用了如果需要继续写得重新创建。别傻乎乎地在DetachBuffer后再writer.WriteXXX。第三WriteBytes接受的范围比较宽std::vectoruint8_t、原始数组指针都可以隐式转换。但如果传的是char*这类有符号类型编译可能报错或者被当成另一种重载保持用uint8_t是最稳的。4.4 大文件流式读取前面讲ReadTextAsync和ReadBufferAsync都是“一次性读入内存”的方案文件大几 GB 时直接爆内存这时必须走流式读取。auto stream co_await file.OpenAsync(FileAccessMode::Read); auto reader DataReader(stream.GetInputStreamAt(0)); const uint32_t chunkSize 64 * 1024; // 每次处理 64KB while (true) { uint32_t loaded co_await reader.LoadAsync(chunkSize); if (loaded 0) break; std::vectoruint8_t bytes(reader.UnconsumedBufferLength()); reader.ReadBytes(bytes); // 对 bytes 做处理比如写日志、解析、转发 }这个循环的关键在于LoadAsync和ReadBytes的配合。LoadAsync(chunkSize)从流里加载指定数量的字节到DataReader的内部缓冲区返回值是实际加载的字节数如果返回 0说明流已经读完每次循环都把UnconsumedBufferLength()里的剩余字节一次性取走保证下轮循环内部缓冲区是干净的。这里最大的坑是如果你LoadAsync加载了 1MB但只ReadBytes读走前面 100 字节剩下 1MB 左右字节会残留在DataReader内部缓冲区。下轮循环LoadAsync会基于这个残留继续从流读取逻辑就会变得混乱。所以要么每次把所有剩余字节取干净要么严格控制每次加载的量。我用的是“加载多少取多少”的写法实测最稳妥。4.5 读取文件基本信息很多文件处理任务不止读写内容还要拿元信息比如文件大小、修改时间。StorageFile自带一些属性但更完整的信息走GetBasicPropertiesAsyncauto props co_await file.GetBasicPropertiesAsync(); uint64_t size props.Size(); auto modified props.DateModified();DateModified返回的是winrt::Windows::Foundation::DateTime如果要转成FILETIME或者时间字符串可以用winrt::clock辅助转换。文件大小这个字段最常见——做上传进度、文件大小筛选都用得到。另外如果要读取自定义属性比如文件的作者、标题这类文档属性需要走Properties接口和StorageItemContentProperties那个链路要长不少但在某些文档处理场景里是刚需。今天先点到为止后面可以单独开一篇聊文件属性。5. 异步编程避坑指南5.1 co_await 后到底在哪条线程这是 C/WinRT 初学者最容易晕的问题co_await后面的代码到底在哪条线程执行默认规则是如果发起异步操作的线程带有 Windows 消息调度器比如 UI 线程那么异步完成后延续会回到这条线程如果是在后台线程发起的延续大概率也在该线程池线程。给你一个实际场景按钮点击事件里调用PickSingleFileAsync用户选完文件后代码自动回到 UI 线程你直接可以去操作控件。这就是为什么 UI 事件函数里用co_await写起来特别顺——不需要手动切回 UI 线程。但如果你在某个后台任务里比如线程池回调中发起文件读取co_await之后延续还在线程池线程这时你要是去更新 UI 控件就会碰到跨线程访问问题。解决办法是显式把上下文切回 UI 线程co_await winrt::resume_foreground(uiDispatcherQueue); // 回到 UI 线程可以更新界面uiDispatcherQueue是 UI 线程的DispatcherQueue对象WinUI 3 和一般桌面应用里都能拿到。记不住具体获取方式没关系关键是知道有线程上下文这回事遇到“有时候行、有时候不行”的怪问题先怀疑线程上下文。5.2 fire_and_forget 的异常无处可逃在 UI 事件处理函数里我经常用winrt::fire_and_forget作为协程返回类型因为它允许协程以异步方式运行而事件系统不需要等待它完成。比如winrt::fire_and_forget MainPage::OnLoadButtonClicked(...) { auto file co_await picker.PickSingleFileAsync(); if (file nullptr) co_return; auto text co_await FileIO::ReadTextAsync(file); UpdateTextView(text); }看起来很完美但有个致命细节如果协程体内抛出异常而你没有捕获整个进程会直接终止。普通函数顶多是异常向上传播fire_and_forget根本没有人接这个异常。所以只要用了fire_and_forget函数体里建议全包一层try/catchwinrt::fire_and_forget MainPage::OnLoadButtonClicked(...) { try { // 异步逻辑 } catch (winrt::hresult_error const ex) { ShowError(ex.message()); } }这个习惯我是在一次线上崩溃后养成的。当时文件路径突然不可访问异步操作抛异常应用当场崩掉根因就是漏了 catch。5.3 版本兼容老 SDK 遇到新 APIWinRT 的 API 是按 Windows 版本分批加入的同一段代码在不同系统上运行可能某些接口不存在。如果你的应用定位是“支持尽量多的 Windows 版本”建议在调用可选 API 前做一次运行时检查#include winrt/Windows.Foundation.Metadata.h bool available winrt::Windows::Foundation::Metadata::ApiInformation:: IsMethodPresent(LWindows.Storage.StorageFile, LGetFileFromPathAsync);这样就能在老系统上优雅降级而不是直接崩溃。实际开发中我一般只在用较新 API 时才加这个检查老牌 API 比如FileIO::ReadTextAsync从最早版本一直有没必要每次查。还有一个版本相关的坑是编译器投影问题。某些 API 在你的开发环境里能编译通过但部署到老系统上运行时会抛“接口不存在”异常这个问题排查起来隐蔽得很。解决方案就是上面这个ApiInformation检查或者直接抬高最低目标版本省一桩心事。6. 常见问题与排查速查6.1 文件打不开八成是权限如果你遇到“文件访问被拒绝”或者“路径不存在”异常先别急着怀疑代码逻辑按照这个顺序排查第一确认路径本身存在。GetFileFromPathAsync对不存在的路径会直接抛0x80070002文件不存在或0x80070003路径不存在。先拿资源管理器开一下这个路径不要想当然。第二确认当前运行环境有没有权限。打包应用需要声明能力非打包桌面应用则看进程的完整性级别。我自己遇到的案例里最常见的其实是“沙盒应用访问了能力之外的位置”。这时要么改走文件选择器要么在清单里加对应能力。第三确认文件没有被其他进程独占。如果一个日志文件正被别的程序以独占模式打开写入时会报共享冲突错误码一般是0x80070020。这种问题通常不是代码 bug而是文件使用方之间的协调问题。6.2 中文路径与编码中文路径问题我建议从一开始就统一规范代码里所有硬编码路径都用宽字符字面量比如LC:\\数据\\文件.txt。因为hstring内部就是 UTF-16宽字符字面量直接对齐不会经过任何转换。如果你拿到了一个std::string比如来自某个配置文件要转成hstring时用winrt::to_hstring但这个转换默认按 UTF-8 解释输入。如果你的std::string实际是 GBK 或者 ANSI转换出来的字符串就会乱码拼接出的路径自然找不到文件。这本质上是源字符串编码不统一的问题解决方法是保证链路里所有非hstring字符串都是 UTF-8或者尽早转成宽字符串。文本内容的中文乱码是另一个高频问题。前面提过ReadTextAsync默认 UTF-8如果你读到一个 GBK 编码的文件尽量用指定编码的重载winrt::hstring contents co_await FileIO::ReadTextAsync(file, UnicodeEncoding::Utf8);如果实在不知道文件编码可以用DataReader读前几个字节判断 BOM再做对应的解码处理。6.3 常用 HRESULT 速查排除问题时异常里的HRESULT是定位的第一手证据。下面是我常遇到的几个做成表格方便你对照错误码含义常见场景0x80070002文件不存在路径写错、文件被移动0x80070003路径不存在目录或多级路径错误0x80070005访问被拒绝权限不足、能力缺失0x80070020共享冲突文件被其他进程独占占用0x80004005未知失败通用错误需要看附加信息拿到错误码后最好再用ex.message()看描述很多 WinRT 异常会附带上层信息能帮你定位是哪一步出的问题而不只是一个泛泛的“失败”。6.4 调试文件代码的小技巧文件处理的调试比普通逻辑调试要麻烦一点因为出错的现场很容易被异步操作掩盖。我常用的几个技巧分享出来。第一打印路径。在获取StorageFile后立刻把file.Path()输出到调试输出窗口OutputDebugStringW(file.Path().c_str());这样即使后面操作失败至少能确认拿到的路径是啥。第二对异步调用的返回值不要偷懒。co_await的返回值直接用局部变量接住不要图省事把它当临时量到处传。因为StorageFile这类 WinRT 对象是引用计数的智能指针局部变量能保证生命周期清晰。第三做文件读写时先把逻辑拆成“获取文件对象”和“执行读写”两个阶段分别打日志。很多问题出在第二阶段但日志只显示第一阶段成功调试方向就完全偏了。第四复杂的数据结构建议先存成 JSON 文本调试等逻辑稳定后再切二进制格式。文本格式出错时一眼就能看出来二进制格式一旦写错排查成本会高好几个量级。最后说点我自己的体会。文件处理怎么看都是基础功能但我在实际项目里为“文件打不开”“中文乱码”“异步回调丢线程”这些问题排查过很长时间。C/WinRT 的好处是 API 统一坏处是学习曲线比传统 Win32 陡一些尤其是异步模型和权限约束必须一开始就从思想上接受。我现在的习惯是每个涉及文件的功能都先明确三件事——权限从哪里来、路径怎么来、异常怎么处理想清楚了再动手写后续能省下大量的调试时间。这篇把文本、二进制、流式和常见坑都过了一遍实际项目里遇到类似需求直接照着改参数就能用希望你能少走几条弯路。
