简介面向C# WinForm开发者与企业内网文件传输场景这份代码示例围绕“上传本地文件到服务器共享文件夹”展开基于VS2010实现从文件选择、共享路径连接、流式读写到进度反馈的完整流程。压缩包共23个文件约36KB以6个cs源码文件为核心配合sln解决方案、csproj项目配置、resx/resources资源文件及exe、pdb、cache等编译产物结构紧凑便于直接打开运行与调试。已有1429人学习说明其在WinForm文件上传与共享目录访问这一常见需求中具有参考价值。读者可从中了解NetworkCredential连接共享路径、FileStream与NetworkStream配合传输、BackgroundWorker异步更新进度条以及文件不存在、权限不足等异常处理思路适合需要快速搭建企业内网文件上传模块或学习C#网络与IO编程的开发者借鉴。1. WinForms 把文件上传到共享文件夹这件事现场比想象中脏某公司内部工单系统的客户端是 WinForms附件不让进数据库只能写到机房一台文件服务器上的共享目录。现场没有对象存储也没有 FTP能给的只有一条 UNC 路径和一个账号。把上传文件到共享文件夹做扎实比想象中麻烦路径写法、凭据挂载、大文件进度、断线重试任何一处没考虑到程序就会在客户现场出问题。这篇按实际交付顺序拆一遍适合正在做桌面端附件上传、又不方便引入额外中间件的同行。2. 路径与凭据UNC 写法、会话挂载和上传方式的取舍动手写代码之前有两个问题必须先定下来目标地址用哪种形式表达身份用哪种方式带进去。这两件事定错了后面写多少重试逻辑都救不回来——血泪经验是八成的“上传失败”其实根本没进到写文件那一步。2.1 共享路径的三种写法与解析顺序同样是“文件服务器上的一个目录”在 Windows 里至少有三种表达方式适用场景完全不同写法示例适用场景主要限制UNC 路径\\fileserver\attach$\inbox通用推荐名称解析依赖 NetBIOS/DNS映射盘符Z:\inbox人工操作、临时脚本盘符是登录会话级的服务里看不到长路径前缀\\?\UNC\fileserver\attach$\inbox路径超过 260 字符需要 .NET 配置或清单配合映射盘符这个坑很多人第一次踩是因为在开发机上把共享挂成了Z:盘代码里写死Z:\inbox本地跑得好好的装到客户机上换成服务方式运行直接抛DirectoryNotFoundException。原因是盘符映射记录在交互式登录会话里Windows 服务跑在 Session 0看不到当前用户的映射表。稳妥做法是全程用 UNC。共享名后面的$只是让资源在“网络”里不显示不影响访问但要注意路径字符串里反斜杠的转义C# 里写成\\fileserver\attach$\inbox比\\\\fileserver\\attach$\\inbox可读得多。路径长了以后客户喜欢用“项目名日期客户名版本号”层层套目录会撞上 260 字符的 MAX_PATH 限制。解决办法是先拼\\?\UNC\前缀再在app.config里关掉旧路径处理configuration runtime AppContextSwitchOverrides valueSwitch.System.IO.UseLegacyPathHandlingfalse;Switch.System.IO.BlockLongPathsfalse / /runtime /configuration这两个开关必须同时给只关一个仍然会抛PathTooLongException。另外注意加了\\?\前缀之后路径里不能再出现/也不能有..这种相对段必须是一条完整的绝对路径所以拼路径时用Path.Combine之后还要做一次规范化。2.2 凭据怎么带进去WNetAddConnection2 与 net use 的取舍能访问共享目录的身份有三种来源一是进程身份。程序以域账号运行或服务登录身份就是有权限的域账号共享访问直接用这个身份代码里不需要做任何事。这种方式最干净但要求客户 IT 愿意给你一个专用账号很多现场谈不下来。二是预先用net use挂载。部署脚本里跑一条net use \\fileserver\attach$ /user:YOURDOMAIN\uploader 密码程序再去访问。问题在于这条命令建立的是当前会话的连接换个用户、重启机器就没了而且密码会留在命令历史里。三是代码里显式挂载。调用mpr.dll的WNetAddConnection2在进程内建立到共享的连接不占盘符靠WNetCancelConnection2释放。这是桌面端最常见也最可控的做法using System; using System.ComponentModel; using System.Runtime.InteropServices; internal static class ShareConnector { [StructLayout(LayoutKind.Sequential)] private class NetResource { public int Scope 0; // RESOURCE_GLOBALNET public int Type 1; // RESOURCETYPE_DISK public int DisplayType 0; public int Usage 0; public string LocalName null; // 传 null不占用盘符 public string RemoteName; // \\server\share注意只到共享名不带子目录 public string Comment null; public string Provider null; } [DllImport(mpr.dll, CharSet CharSet.Unicode, SetLastError true)] private static extern int WNetAddConnection2( NetResource netResource, string password, string username, int flags); [DllImport(mpr.dll, CharSet CharSet.Unicode, SetLastError true)] private static extern int WNetCancelConnection2(string name, int flags, bool force); public static void Connect(string uncRoot, string user, string password) { var nr new NetResource { RemoteName uncRoot }; int rc WNetAddConnection2(nr, password, user, 0); if (rc ! 0) throw new Win32Exception(rc, $挂载共享失败错误码 {rc}); } public static void Disconnect(string uncRoot) { WNetCancelConnection2(uncRoot, 0, true); // forcetrue断开时不等待句柄关闭 } }几个参数要说清楚。RemoteName只能给到共享这一层比如\\fileserver\attach$不能直接给\\fileserver\attach$\inbox给了会返回错误码 67找不到网络名。flags传 0 表示持久连接但不保存凭据传CONNECT_TEMPORARY值 4则连接在进程退出后自动失效做一次性上传更合适。WNetCancelConnection2的force参数传true是为了避免还有文件句柄没关时断开被卡住。返回码是最有用的排错入口几个高频值记一下错误码含义常见根因53找不到网络路径网段不通、名称解析失败、共享未开启67找不到网络名共享名拼错或路径带到了子目录5拒绝访问账号无权限或共享权限与 NTFS 权限取交集后为空1326用户名或密码错误密码过期、账号被锁、域名写错1219多重连接冲突已有到同一服务器的其他凭据会话86密码无效旧版协议下的凭据校验失败1219 这个特别值得单说。Windows 对同一台服务器只保留一套凭据会话如果用户之前用个人账号在资源管理器里访问过这台服务器你的程序再用上传专用账号连就会拿到 1219。处理办法是在连接前先WNetCancelConnection2断一次或者干脆用服务器的另一个访问入口IP 和主机名算两个入口绕开。2.3 上传方式选型File.Copy、流式复制、后台队列最省事的写法是File.Copy(local, unc, true)。它确实能在共享路径之间复制文件但有两个硬伤没有进度、不能取消。小文件几十 KB 的截图无所谓几百 MB 的附件包就会让界面看起来像死机用户点两次按钮就开始并发上传。流式复制是主力方案自己开FileStream按固定大小缓冲区循环读写每轮上报一次进度CancellationToken随时能中断。代价是要自己处理临时文件、校验和异常清理。后台队列适用于“允许延迟、不允许失败”的场景比如把附件先落在本地%LocalAppData%下的待传目录后台线程按顺序推送到共享界面只负责入队。弱网现场这个思路能显著降低用户投诉——上传失败不影响业务操作重连后自动补传。缺点是本地要留暂存空间还要做去重和过期清理。我一般的判断标准是单文件小于 10 MB 且网络在同一个局域网内File.Copy加个Task.Run就够了超过这个量级或者客户端分布在不同办公点直接上流式复制加临时文件如果业务明确要求“断网也不能丢附件”再考虑队列。3. 最小可运行一个带进度、可取消的 WinForms 上传窗体这一章给出一个能直接跑起来的版本。界面尽量简单重点是后台方法的结构和几个容易写错的地方。3.1 界面与状态机四个控件就够窗体上放txtFile源文件路径带回车选择、txtShare目标共享目录、btnUpload上传、btnCancel取消、progressBar进度、lblStatus状态文本。值得注意的是不要在按钮事件里直接File.Copy也不要用BackgroundWorker——async/await加IProgressT已经把线程切换的事处理干净了ProgressT会自动把回调投递回 UI 线程的SynchronizationContext不需要手写Invoke。// 进度载体避免在回调里反复算百分比 public readonly struct UploadProgress { public long Copied { get; } public long Total { get; } public UploadProgress(long copied, long total) { Copied copied; Total total; } public int Percent Total 0 ? 100 : (int)(Copied * 100L / Total); } private CancellationTokenSource _cts; private async void btnUpload_Click(object sender, EventArgs e) { var source txtFile.Text.Trim(); if (!File.Exists(source)) { lblStatus.Text 源文件不存在; return; } var shareRoot txtShare.Text.TrimEnd(\\); var target Path.Combine(shareRoot, BuildTargetName(source)); // 硬超时兜底SMB 写操作在链路中断时可能长时间不返回 _cts new CancellationTokenSource(TimeSpan.FromMinutes(30)); var progress new ProgressUploadProgress(p { progressBar.Value Math.Min(p.Percent, 100); lblStatus.Text ${p.Copied / 1048576.0:F1} MB / {p.Total / 1048576.0:F1} MB; }); btnUpload.Enabled false; btnCancel.Enabled true; try { await UploadService.UploadAsync(source, target, progress, _cts.Token); lblStatus.Text 上传完成; } catch (OperationCanceledException) { lblStatus.Text 已取消或超时; } catch (IOException ex) { lblStatus.Text 网络或文件错误 ex.Message; } finally { btnUpload.Enabled true; btnCancel.Enabled false; _cts.Dispose(); _cts null; } } private void btnCancel_Click(object sender, EventArgs e) _cts?.Cancel();Math.Min(p.Percent, 100)是防止总长度在读取过程中变化源文件被别的程序追加写入导致进度条超出范围抛异常。_cts用CancelAfter而不是只在取消按钮里 cancel是因为网络设备的超时往往比用户耐心长得多必须有一道兜底。3.2 核心上传方法分块读写与进度回调真正的复制逻辑单独放到一个静态类里方便单测和复用public static class UploadService { private const int BufferSize 1024 * 1024; // 1 MB public static async Task UploadAsync( string sourcePath, string targetPath, IProgressUploadProgress progress, CancellationToken token) { var total new FileInfo(sourcePath).Length; var buffer new byte[BufferSize]; long copied 0; long lastReport 0; using (var src new FileStream(sourcePath, FileMode.Open, FileAccess.Read, FileShare.Read, BufferSize, FileOptions.SequentialScan | FileOptions.Asynchronous)) using (var dst new FileStream(targetPath, FileMode.Create, FileAccess.Write, FileShare.None, BufferSize, FileOptions.Asynchronous)) { int read; while ((read await src.ReadAsync(buffer, 0, buffer.Length, token) .ConfigureAwait(false)) 0) { await dst.WriteAsync(buffer, 0, read, token).ConfigureAwait(false); copied read; // 1 MB 回调一次太密用 8 MB 或 200 ms 做节流 if (copied - lastReport 8 * BufferSize || copied total) { progress?.Report(new UploadProgress(copied, total)); lastReport copied; } } await dst.FlushAsync(token).ConfigureAwait(false); } } }FileOptions.SequentialScan告诉系统顺序读、可以提前预读FileOptions.Asynchronous让ReadAsync/WriteAsync走真正的异步 I/O而不是在线程池里假异步。ConfigureAwait(false)是因为后面没有 UI 操作避免每次 await 都把上下文切回 UI 线程。FileShare.None用在目标文件上是故意让第二个写同一目标文件的进程直接失败而不是两边交叉写入产生半截内容。源文件用FileShare.Read允许别人同时读但不允许写。进度回调的节流很有必要。1 MB 缓冲区意味着 1 GB 文件要回调一千次如果每次都在 UI 线程重绘进度条和字符串光是界面刷新就能拖掉一成吞吐。用 8 MB 一报或者用Stopwatch控制 200 毫秒一报视觉上完全看不出差别。3.3 取消、超时与重试的边界CancellationToken只对循环的检查点生效如果某次WriteAsync卡在 SMB 层不返回token 是唤不醒它的。所以超时不能只靠 token还要有外层兜底Task.WhenAny(uploadTask, Task.Delay(timeout))超时后把任务标记为失败并清理临时文件线程本身交给系统回收。重试要克制。网络瞬断、共享暂时不可达错误码 53可以重试UnauthorizedAccessException重试一百次也没用。常见做法是最多三次间隔 2、4、8 秒递增for (int attempt 1; ; attempt) { try { await UploadAsync(source, tempPath, progress, token); break; } catch (IOException) when (attempt 3 !token.IsCancellationRequested) { await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), token); progress?.Report(new UploadProgress(0, total)); // 重置进度显示 } }注意when过滤条件里加了!token.IsCancellationRequested否则用户点了取消还会被重试逻辑强行拉起来再传一次。3.4 目标目录创建与重名文件的处理Directory.CreateDirectory在 UNC 路径上是可用的只要账号有权限会把中间缺失的层级一起建出来。但共享层面的权限共享权限和文件夹层面的权限NTFS 权限是两套取交集生效很多人只加了共享的“完全控制”就去排查为什么还报拒绝访问白耗一下午。重名文件的策略要和业务方确认清楚常见三种覆盖、跳过、改名保留。改名保留最安全用“时间戳 原文件名”的组合private static string BuildTargetName(string sourcePath) { var name Path.GetFileNameWithoutExtension(sourcePath); var ext Path.GetExtension(sourcePath); // 去掉路径分隔符等非法字符防止拼接出意外目录 name string.Concat(name.Split(Path.GetInvalidFileNameChars())); return ${DateTime.Now:yyyyMMdd_HHmmss}_{name}{ext}; }如果业务要求“同一文件重复上传只保留一份”那就不能用时间戳得用内容哈希做文件名先算 SHA256 再拼扩展名天然去重。这个在附件场景里很实用代价是每次上传前都要完整读一遍源文件。4. 大文件写入共享目录临时文件、哈希校验与续传的取舍超过几百 MB 之后前面那套代码还能跑但会暴露出几个新问题吞吐上不去、失败后留下垃圾、别人可能读到写了一半的文件。4.1 缓冲区大小与 SMB 的实际吞吐缓冲区不是越大越好。512 KB 在高延迟链路上会明显偏慢因为每次往返搬运的数据少1 MB 到 4 MB 是常见区间再往上收益递减还会让每个并发上传占掉几十 MB 托管内存。如果客户端是 32 位进程默认的 2 GB 用户态地址空间本来就不宽裕4 MB 缓冲区乘上十几个并发很容易 OOM。我的习惯是把它做成配置项默认 1 MB遇到跨城专线或者移动网络再往上调。判断依据很简单在本机到共享目录之间传一个 500 MB 的测试文件看任务管理器里的网络占用能不能跑到链路带宽的七成以上跑不到就试着把缓冲区翻倍再测一次两次没改善就说明瓶颈不在缓冲区。另外要注意FlushAsync只保证数据交给了操作系统不保证已经落到文件服务器的磁盘上。真要确认落地需要用Flush(true)但那会显著拖慢速度一般只在关键附件上开。4.2 .tmp 写入 改名避免半截文件被别人读到直接往目标文件写中途失败就会在共享目录里留下一个“看起来正常、实际残缺”的文件。下游有定时任务扫描这个目录做入库扫到半截文件就会解析失败然后再也补不回来了——这是最典型的翻车姿势。正确做法是先写同目录下的临时文件写完再改名public static async Task UploadAtomicAsync( string sourcePath, string targetPath, IProgressUploadProgress progress, CancellationToken token) { var dir Path.GetDirectoryName(targetPath); var tempPath Path.Combine(dir, . Path.GetFileName(targetPath) . Guid.NewGuid().ToString(N) .tmp); try { await UploadAsync(sourcePath, tempPath, progress, token).ConfigureAwait(false); // 同一共享内改名是元数据操作几乎不产生数据搬运 if (File.Exists(targetPath)) File.Delete(targetPath); File.Move(tempPath, targetPath); } catch { // 失败必须清理否则共享目录会积累一堆点开头的垃圾 try { if (File.Exists(tempPath)) File.Delete(tempPath); } catch { /* 清理失败不掩盖原始异常 */ } throw; } }临时文件名以点开头并且带 GUID是为了避开下游扫描规则同时防止并发上传时两个进程抢同一个临时文件名。File.Move在同一个共享内是重命名不搬数据因此开销可以忽略。File.Exists加File.Delete再Move这三步之间有一个极短的窗口期如果下游正好在这一刻读文件会读不到。要求严格的话可以用File.Replace它在同一卷内是原子的但要求目标文件已存在且支持备份参数在 SMB 上的行为依赖服务端实现用之前建议在目标环境实测一次。4.3 校验与失败回滚传完之后要不要校验取决于附件的性质。合同扫描件、报表归档这类“错了要出事”的做一次 SHA256 对比普通截图、日志打包比对一下字节长度就够了因为读回来再算一遍哈希等于把 I/O 翻倍。private static string ComputeSha256(string path) { using (var sha System.Security.Cryptography.SHA256.Create()) using (var fs new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, 1 20, FileOptions.SequentialScan)) { return BitConverter.ToString(sha.ComputeHash(fs)).Replace(-, ); } }校验失败的处理只有一条路删掉目标文件把任务标记为失败让人工或者队列重来。不要试图“部分保留”SMB 上没法保证残留内容对应哪一段。4.4 断点续传值不值得做技术上可行目标文件已经存在时用FileMode.Open打开Seek到已有长度源文件也Seek到同样位置继续写。判断依据用“长度 最后写入时间”两者都一致才续传否则从头来。但要注意续传的前提是目标文件在写入过程中对其他人不可见否则下游会读到拼接中的内容。这就是为什么续传和.tmp方案要配套临时文件天然不被人扫续传时对临时文件做追加就行写完再改名。我的建议是 500 MB 以下不做续传重传的成本比维护这套状态的复杂度低得多。真正需要续传的是那种“一个附件几个 G、客户端还在弱网环境”的场景那时候除了续传还得配合本地暂存和分片索引工程量完全不是一个量级。5. 避坑与排查五类现场故障的现象、原因和解法下面这几条都是实际交付里反复出现的按“现象 → 原因 → 解决”整理排查命令可以直接抄。5.1 开发机正常客户机报“找不到网络路径”错误码 53现象同一份程序在你机器上跑得好好的到了客户现场第一次点上传就抛IOException内部错误码 53。原因一是客户端和文件服务器不在同一网段中间有防火墙拦了 445 端口二是主机名解析不了客户内网的 DNS 里根本没有那条 A 记录只能靠 WINS 或者 hosts三是共享名写错把attach$写成了attach。解决按顺序验三层。先在命令行ping fileserver看名称能不能解析再net view \\fileserver看共享列表是否可见最后net use \\fileserver\attach$ /user:YOURDOMAIN\uploader手工挂一次看返回什么错误码。三层都过程序里基本不会再有 53。防火墙这层要确认 445 出站放行很多客户的终端安全策略默认只放行 139。5.2 上传专用账号连不上报 1219 多重连接冲突现象用个人账号在资源管理器里访问过共享之后程序里用上传账号连接稳定复现 1219重启程序也没用。原因Windows 对同一台服务器只维护一套网络凭据会话先到先得。资源管理器已经用个人账号建立了会话程序再用另一个账号连同一台服务器就会被拒。解决连接前先断开已有会话。net use \\fileserver\IPC$ /delete /y代码里对应在Connect之前调一次ShareConnector.Disconnect(uncRoot)然后把返回码忽略掉。另一个绕法是用 IP 访问共享\\10.0.0.10\attach$Windows 认为这是另一个服务器名会另开一套会话——能解燃眉之急但属于利用未定义行为不建议长期这么写。5.3 共享权限给了“完全控制”仍然拒绝访问错误码 5现象IT 在共享属性里把上传账号加进了“完全控制”程序还是抛UnauthorizedAccessException。原因Windows 的共享权限和 NTFS 权限是两套最终权限取交集。共享权限放开了但目标文件夹的 NTFS ACL 里没有这个账号照样进不去。还有一种情况是账号本身没通过身份验证比如密码过期此时报的也可能是 5 而不是 1326。解决让 IT 在目标目录上执行icacls确认或者用上传账号在服务器本机登录后手工往目录里写一个文件验证。程序侧可以先用Directory.Exists(shareRoot)做一次探活这个调用会触发权限检查比直接写文件更早暴露问题。5.4 进度条卡在 99%然后超时现象大文件上传到最后一点就不动了界面无响应半小时后报超时共享目录里留下一个大小几乎正确的残缺文件。原因数据已经发完卡在关闭句柄或者服务端杀毒扫描上。目标目录如果开了实时扫描文件关闭时会被完整扫一遍几个 G 的文件能扫出几十秒到几分钟。另外客户端网络切换比如笔记本从有线切到无线会让已建立的 SMB 会话失效写入挂起直到 TCP 超时。解决一是把目标目录加进服务端的扫描排除列表这一条要和客户 IT 谈二是在代码里给关闭和刷新单独设一个较短的超时超时就直接判定失败并清理临时文件三是把FlushAsync放在循环外面不要每写一块刷新一次那会让扫描触发得更频繁。5.5 路径稍微长一点就报 PathTooLongException现象目录层级深一点的客户环境Path.Combine出来的路径超过 260 字符直接抛异常连文件都没开始传。原因.NET Framework 默认走旧版路径处理受 MAX_PATH 限制。解决三步一起做。app.config里加AppContextSwitchOverrides两个开关应用程序清单里声明longPathAware代码里对拼接结果做一次判断超长就转成\\?\UNC\前缀形式。注意转换时要把开头的\\换成\\?\UNC\中间的反斜杠保持原样转换完不要再做任何路径规范化否则前缀会被吃掉。6. 配置化与上线前验证把共享目录从代码里挪出去共享路径、账号、缓冲区大小这些值一开始就别写死在代码里。客户换个文件服务器你不该重新编译一次。用appSettings起步足够appSettings add keyUpload.ShareRoot value\\fileserver\attach$\inbox / add keyUpload.User valueYOURDOMAIN\uploader / add keyUpload.BufferSize value1048576 / add keyUpload.TimeoutMinutes value30 / /appSettings密码不要跟着配置文件走。桌面端可以用 DPAPI 的ProtectedData.Protect按当前用户加密后存在本地或者干脆让 IT 在客户端机器上手工配一次 Windows 凭据服务端场景则优先让进程以域账号运行配置里只留用户名。配置文件里出现明文密码交付审计那一关基本过不去。上线前我会强制走一遍这张表少一项都不签字检查项动作通过标准名称解析ping文件服务器主机名能解析到正确 IP共享可达net view \\fileserver能看到目标共享名凭据有效net use手工挂载返回 0无 1219/1326权限足够用上传账号手工写一个文件写入成功且可删除磁盘余量服务器侧查看目标卷剩余空间大于单次上传上限的 5 倍长路径构造一条 300 字符的路径做一次上传不抛 PathTooLongException杀毒排除确认目标目录已排除实时扫描大文件关闭耗时正常其中“磁盘余量”这一条最容易被忽略。共享目录没人管一年下来塞满是很常见的事写满之后报的错误是IOException错误信息里只有“磁盘空间不足”几个字但用户看到的是“上传失败”然后来找你。还有一种情况值得提前想好文件服务器做维护窗口时共享会不可达WNetAddConnection2直接返回 53。这时候程序不应该崩溃也不应该给用户弹一堆技术错误最好的处理是把附件先落到本地暂存目录标记为待传在后台每隔几分钟探一次共享是否恢复恢复了自动补传。这个逻辑做起来不难但能让客户在服务器维护那天完全不感知。我第一次交付这类功能时图省事直接File.Copy加一个Thread.Sleep假进度结果客户那边上传一个 300 MB 的扫描件中途网络抖动目录里留下了一个半截文件下游定时任务把它当成完整附件入库第二天对账差了十几万。从那以后我每次做共享目录上传不管文件多小都强制走“临时文件 校验 改名”这一套进度和超时也一律写全再也不靠运气。希望帮到你。本文还有配套的精品资源点击获取