简介面向 C# 开发者的实战源码解决基于 Windows 窗体把本地文件上传到局域网共享文件夹的典型需求。该场景常见于内部系统文件归档、资料分发与协同办公。项目在 VS2010 环境下编写完整涵盖文件选择、共享路径连接、文件流读写、进度显示、异常处理及安全限制等环节适合企业内部数据互传也适合想掌握文件网络操作的开发者。压缩包共 23 个文件以源代码、可执行程序、调试信息和工程配置文件为主整体仅 36KB包含窗体界面逻辑、设置配置及完整解决方案结构紧凑。已有 1426 人学习下载。通过研读源码可掌握网络凭据认证连接共享目录、异步更新进度条、文件类型与大小安全校验等实用技巧并借鉴网络断开、权限不足等错误处理思路稍作改造即可复用于实际业务。1. WinForm 上传文件到共享文件夹先解决“写不进去”再谈性能本地工具型系统里把文件从 WinForm 客户端传到服务器的共享文件夹是个看起来简单、做起来容易翻车的需求。某项目X里业务部门要求把导出的报表直接写进一个局域网共享路径我最初以为 File.Copy 一行就能收工结果在生产环境里被权限、并发、路径长度连续教育。下面把完整方案拆开先讲共享连接的原理再给 File.Copy 到流式上传的代码演进最后总结几条排查经验。适合刚接手 WinForm 办公自动化、又不想搭 FTP 或 HTTP 上传服务的开发者也适合被“写不进去”和“传了一半”折磨过的熟手。2. 连接共享文件夹凭据、UNC 与驱动盘映射的取舍要理解为什么 File.Copy 有时候失败得先明白共享访问的模型。Windows 共享基于 SMB 协议客户端发起请求时系统会用当前进程的安全令牌去协商访问权限。你的 WinForm 程序跑在用户会话里令牌来自登录用户如果这个用户没有共享目录的写权限或者压根没有共享访问权限File.Copy 就会抛 UnauthorizedAccessException。在很多公司里客户端机器的登录账号和文件服务器的账号体系并不互通尤其是不在域环境里的时候默认令牌很难直接命中共享目录的 ACL。2.1 匿名访问为什么在办公环境里行不通最常见的失败现场是共享文件夹明明开了 Everyone 读/写客户端还是报没有权限。原因是 Windows 默认的 Guest 账户在大多数系统上是被禁用的现代桌面系统默认关闭不安全的来宾登录。即使共享端开了 Everyone客户端以匿名身份访问时系统会尝试把匿名请求映射到 GuestGuest 禁用就直接拒绝。所以靠开 Everyone 不能作为生产环境的上传方案这条我栽过跟头。工程上的常规做法是建立一个专用共享账号。某公司通常维护两个账号一个只读供下载报表用一个只写专门交给客户端程序。这个账号只需要锁在文件服务器本地即可如果文件服务器加入了域也可以用专门的域账号。要在代码里传账号密码必须显式建立一个网络连接而不是依赖当前进程的默认令牌。所谓显式建连就是代码里调用 Windows 的 WNet 系列 API让当前进程持有指定账号的网络会话。2.2 WNetUseConnection 建立会话下面的代码封装了共享连接的核心逻辑粘贴到工具类里就能用using System; using System.Runtime.InteropServices; public class ShareConnector { [StructLayout(LayoutKind.Sequential, CharSet CharSet.Unicode)] internal struct NETRESOURCE { public int dwScope; public int dwType; public int dwDisplayType; public int dwUsage; public string lpLocalName; public string lpRemoteName; public string lpComment; public string lpProvider; } [DllImport(mpr.dll, CharSet CharSet.Unicode, SetLastError true)] internal static extern int WNetUseConnection( IntPtr hwndOwner, ref NETRESOURCE lpNetResource, string lpPassword, string lpUserName, int dwFlags, out int lpAccess, IntPtr lpBuffer, ref int lpBufferSize); public static bool Connect(string server, string share, string user, string password) { var res new NETRESOURCE { dwType 1, // RESOURCETYPE_DISK lpRemoteName $\\\\{server}\\{share} }; int access 0; int bufferSize 0; int result WNetUseConnection( IntPtr.Zero, ref res, password, user, 0x04, // CONNECT_TEMPORARY out access, IntPtr.Zero, ref bufferSize); return result 0; } }逻辑说明lpRemoteName 使用 UNC 格式 \server\share这是显式访问共享的标准写法dwType 固定 1 表示磁盘资源CONNECT_TEMPORARY 是 0x04表示会话不保存到系统持久映射里重启后不会自动重连。返回值 0 表示成功非 0 是系统错误码。WNetUseConnection 建立的是当前进程可用的网络会话之后 File.Copy 或 Directory.GetFiles 就能以该凭据访问目标。注意 hwndOwner 传 IntPtr.ZeroUI 线程下不会弹认证框。参数说明server 只要主机名或 IP不要加协议前缀share 是共享名user 如果是域账号写成 domain\user本地账号则写 server\user。密码为空时系统会尝试用当前用户凭据所以不要依赖这个特性显式传。bufferSize 传 0 时 WNetUseConnection 会自动分配内部缓冲不需要手动申请。上传结束后释放会话也很关键否则连接会一直占用[DllImport(mpr.dll, CharSet CharSet.Unicode, SetLastError true)] internal static extern int WNetCancelConnection2(string lpName, int dwFlags, bool fForce); // 用完断开防止会话堆积 WNetCancelConnection2(\\srv-file\report, 0, false);2.3 驱动盘映射与 UNC 直连的取舍有了凭据会话还要决定使用哪种路径风格。驱动盘映射需要先申请一个盘符net use Z:这个盘符对整台机器是全局的如果客户端机器上有多个使用者盘符会互相冲突而且映射后系统会把凭据持久化到用户配置里遗留隐患更多。UNC 直连没有盘符问题代码里直接用 \server\share\子目录\文件名路径可读性也更强我一般都会选后者。服务器端默认最多支持数十个并发客户端会话一台客户端可以建立多条 TCP 会话但无限创建会话会占用服务器内存。用完立刻 WNetCancelConnection2 是必要的。返回码污染也是一个典型问题——Error 1219 表示已有连接使用不同凭据需要先断开旧连接再连新账号Error 67 表示找不到网络名多半是防火墙或 SMB 协议版本问题。下面几个返回码是我在实际排查中常遇到的错误码含义处理建议0连接成功继续上传流程1219已用其他凭据连接先 WNetCancelConnection2 再重连67找不到网络名检查共享名、SMB 协议版本、防火墙5拒绝访问检查账号密码及共享 ACL59意外的网络错误确认 445 端口连通检查网络策略3. 上传实现从 File.Copy 到可取消的流式上传连接建立后上传本身反而成了需要细抠的部分。业务需求通常不只是“把文件弄过去”还要考虑覆盖策略、大文件响应、取消操作和进度反馈。这一章按代码演进顺序写从最简单的一行流式上传开始。3.1 最小可用版本File.Copy 直传string remotePath \\srv-file\report\20250401\orders.xlsx; string localPath D:\export\orders.xlsx; bool overwrite true; File.Copy(localPath, remotePath, overwrite);逻辑说明File.Copy 是最短路径参数 3 为 true 表示目标文件存在时覆盖。它的内部实现也是打开目标文件后分块写入但它没有进度回调也不支持取消只能一直阻塞到完成或抛异常。目标目录不存在时File.Copy 不会自动创建目录必须先调 Directory.CreateDirectory(Path.GetDirectoryName(remotePath))这一步在共享路径下同样有效。参数说明overwrite 设 false 时目标已存在会抛 IOException业务上如果需要“存在就跳过”比先 File.Exists 再判断更省一次网络访问。但要注意File.Exists 在共享路径上可能因为缓存出现误判这点在避坑章节展开。这个版本适合 50MB 以下、网络稳定的内部工具先跑通链路再谈优化。3.2 用 FileStream 控制覆盖、追加与写穿当需求不只是“复制”而是“写日志”或“只覆盖部分内容”时File.Copy 就不够用了。这时直接用 FileStream 打开远程文件using (var src new FileStream(localPath, FileMode.Open, FileAccess.Read)) using (var dst new FileStream(remotePath, FileMode.Create, FileAccess.Write, FileShare.Read, 32 * 1024)) { src.CopyTo(dst, 32 * 1024); }逻辑说明FileMode.Create 会先截断目标文件再写入等价于覆盖。FileMode.Append 配合 FileAccess.Write 可以做日志追加多个客户端同时 Append 时系统会以文件锁协调但要注意 SMB 追加在小文件上没问题大文件并发追加有性能问题。FileShare.Read 表示目标文件允许其他进程同时读如果不希望使用者下载到半截文件改成 FileShare.None 更安全。最后一个构造参数选了 32KB 缓冲区共享拷贝时这个值在大多数局域网下表现均衡。参数说明FileStream 的构造重载很多目标路径参数必须确认是有写权限的 UNC 路径否则打开就抛 UnauthorizedAccessException。如果你希望数据实时落到服务器磁盘而不是停在系统缓存里可以加 FileOptions.WriteThrough。但 WriteThrough 会显著降低写入速度大文件上传时不推荐只有要求写后立即可读的协作场景才值得开。3.3 大文件异步上传与取消大文件需要 UI 不冻结还要支持取消。异步版本private async Task UploadAsync(string localPath, string remotePath, IProgressint progress, CancellationToken ct) { await using var src new FileStream(localPath, FileMode.Open, FileAccess.Read, FileShare.Read, 64 * 1024, useAsync: true); await using var dst new FileStream(remotePath, FileMode.Create, FileAccess.Write, FileShare.None, 64 * 1024, useAsync: true); long total src.Length; long written 0; var buffer new byte[64 * 1024]; int read; while ((read await src.ReadAsync(buffer, 0, buffer.Length, ct)) 0) { await dst.WriteAsync(buffer, 0, read, ct); written read; progress?.Report((int)(written * 100L / total)); } }逻辑说明进度计算用 written * 100L / total先把乘数提升为 long避免 int 乘法溢出。IProgress 会在 UI 线程的 SynchronizationContext 上回调所以可以直接更新 ProgressBar。CancellationToken 是取消操作的关键。注意 SMB 写入的中断不能做到真正的“回滚”——已写入的分块会留在目标文件里下次上传如果 FileMode.Create 就会截断重写问题不大但如果目标是 Append可能留下半截内容。建议取消后把目标文件改名或删掉保证文件完整性。参数说明useAsync: true 会采用异步 IO避免线程池线程被磁盘等待阻塞。进度回调频率是每 64KB 一次100MB 文件会回调 1600 次UI 进度条有性能压力时可以在回调里做节流比如只在上一次更新间隔超过 100ms 时才刷新。4. 工程化封装重试、校验与共享目录规划上传功能放进正式项目里光有上传代码不够。共享网络天生的偶发故障、写后读不一致、多客户端撞名都需要在上传逻辑外面再套一层工程化处理。这一章讲重试策略、校验方法和目录规划都属于生产环境必须做的部分。4.1 共享写入的重试策略与超时控制共享上传最容易出现瞬时失败服务器端短暂繁忙、网络闪断、SMB 会话过期。File.Copy 一次失败不代表永远失败常见做法是封装一个重试循环public static async Task RetryUploadAsync(FuncTask uploadFunc, int maxRetries 3) { int delayMs 300; for (int i 0; i maxRetries; i) { try { await uploadFunc(); return; } catch (IOException ex) when (i maxRetries - 1) { await Task.Delay(delayMs); delayMs * 3; } } throw new IOException(上传失败已重试三次); }逻辑说明指数退避从 300ms 开始第二次重试 900ms第三次 2700ms总等待不超过 5 秒适合局域网内共享写入的故障窗口。catch 里只捕获 IOException认证失败或路径错误这类不可恢复异常直接抛出不要浪费重试次数。超时控制要说清楚File.Copy 没有超时参数用 Task.WhenAny 包一层可以做到超时返回但底层 IO 并没有真正取消超时后文件可能还在写。更推荐的做法是把 CancellationToken 传入异步流式上传配合 CancellationTokenSource.CancelAfter(TimeSpan.FromSeconds(30)) 实现真正的超时取消。注意 maxRetries 不要设太大共享目录的瞬时故障一般在 1-3 秒内恢复重试 3 次足够重试间一定加延迟否则服务器端连接堆积会让问题更严重。4.2 上传后的校验长度、时间戳与哈希写完不等于写对。共享目录上的写入服务器端可能因为缓存、权限延迟或磁盘满导致数据不一致所以上传后要做一次校验。我习惯做三个层级的校验按开销从小到大排。第一层是长度校验。上传结束后重新读取目标文件的 Length与本地源文件 Length 比较不一致就报错并标记“半截文件”var localInfo new FileInfo(localPath); var remoteInfo new FileInfo(remotePath); bool lengthOk remoteInfo.Length localInfo.Length;第二层是时间戳校验。共享文件写入之后服务器端的 LastWriteTimeUtc 会更新。但 SMB 目录枚举有缓存刚写完立刻读取可能拿到旧的修改时间因此要延迟 1.5 秒再查。这个延迟看似玄学其实是底层目录缓存的真实行为延迟后再读基本都能拿到最新值。第三层是哈希校验长度和时间戳都可能一致但内容损坏对订单或报表类文件SHA256 校验更可靠。但哈希读取本身要走一次网络开销明显适合文件确实重要且网络带宽充足时使用。注意共享端读取文件会占用一次会话频率不应太密。4.3 共享目录规划与重名策略多客户端同时上传同名文件是常见冲突场景。我的做法是强制按日期和客户端 ID 创建子目录然后给文件加时间戳string remoteDir $\\{server}\{share}\{DateTime.Now:yyyyMMdd}; Directory.CreateDirectory(remoteDir); // UNC 路径下会自动创建共享内目录 string filePart ${clientId}_{DateTime.Now:HHmmssfff}_{Path.GetFileName(localPath)}; string target Path.Combine(remoteDir, filePart);参数说明clientId 建议从配置文件读取不要拿用户输入避免路径注入。时间戳用 HHmmssfff 可以精确到毫秒同一客户端瞬间的重复上传也不会重名。目录按天分还能方便共享端运维定期清理比如只保留 30 天目录。这里要注意 Path.Combine 在 UNC 下虽然可用但现在它不会遇到后续参数以 \ 开头时的坑所以外层统一用 string 拼接更可控格式化成固定模板后审查也方便。5. 避坑指南五个反复出现的共享写入问题共享上传的坑大多不在代码逻辑而在系统环境和并发状态。这一章写五条我在实际交付中踩过的记录每条按现象、原因、解决展开。坑一连接成功但枚举目录报拒绝访问。现象是 WNetUseConnection 返回 0但马上 Directory.GetFiles 却抛 AccessDenied。原因是当前进程之前已经用别的凭据连过同一共享系统内存中存在同名会话WNetUseConnection 返回了成功但并未切换凭据。解决方法是先调用 WNetCancelConnection2 强制断开再重新连接连接完成后延迟 200ms 再访问给网络会话一点建立时间实测有效。坑二32 位程序在 64 位系统上路径被重定向。现象是把文件写到 C:\Windows\System32 下重启后文件找不到。原因是 32 位进程访问 System32 会被自动重定向到 SysWOW64。共享路径是 UNC 不受这个影响但本地源路径如果涉及系统目录就有隐患。解决方法是把 WinForm 项目的目标平台改成 x64 或 AnyCPU或者将本地路径改用 Path.GetTempPath()避免系统目录重定向干扰。坑三对方机器开了防火墙或只支持旧版 SMB。现象是连接时提示找不到网络名但 IP 能 ping 通。原因是共享依赖 TCP 445 端口防火墙只开放了 139 就无法建立 SMB 会话。解决方法是确认服务器防火墙放行 445如果对方是只支持 SMB1 的旧设备需要在 Windows 功能里勾选 SMB1 支持。要注意 SMB1 有安全隐患不建议长期开启尽量推动设备升级。坑四目标文件被其他用户占用。现象是 File.Copy 偶发 IOException提示“另一个程序正在使用此文件”。原因是共享文件被某人的 Excel 或 WPS 打开且以独占方式持有。解决方法是捕获 IOException 后改文件名重试或者返回给用户“目标文件被占用请稍后重试”不要无限重试。坑五路径超过 260 字符。现象是本地程序正常但 UNC 长文件名报 DirectoryNotFound。原因是默认 Win32 API 受 MAX_PATH 限制长路径会被截断。解决方法是使用 \?\UNC\ 前缀扩展格式或者启用 LongPathsEnabled 注册表项再或者缩短共享名和目录层级把嵌套深度压下来。6. 让上传结果可验证三个信号确认文件真的落盘上传交付后运维同事最常问的问题就是怎么确认文件真的进去了只靠 File.Copy 不报错远远不够我后来养成了一个习惯上传完成后强制走三个信号验证每个信号都能独立暴露一类问题。第一个信号是长度校验。上传完成后等待 1.5 秒重新读取远程文件的 FileInfo.Length与本地源文件对比。本地 1,048,576 字节远程必须是相同的数差一个字节都说明写入中断或服务器端出问题。第二个信号是头部字节比对用 FileStream 打开远程文件读取前 16 字节和使用相同的二进制读取方式读本地文件的前 16 字节比较防止“文件存在但内容是旧版本”的情况。第三个信号是目标目录枚举获取目录文件清单并按名称匹配刚上传的文件确认它出现在预期目录下且目录计数正确增加。public bool VerifyUploaded(string localPath, string remotePath) { Task.Delay(1500).Wait(); // 等待目录缓存刷新 var localInfo new FileInfo(localPath); var remoteInfo new FileInfo(remotePath); if (remoteInfo.Length ! localInfo.Length) return false; byte[] localHead ReadHead(localPath, 16); byte[] remoteHead ReadHead(remotePath, 16); return localHead.SequenceEqual(remoteHead); }这套验证逻辑看起来多余但真实帮我抓到过两次问题一次是服务器磁盘满导致写入静默失败另一次是目标目录被运维改了 ACL写入返回成功但实际落到了临时目录。从那以后我每次写完上传功能都会强制把这三个信号走一遍宁可多等 1.5 秒也不让半截文件出现在共享盘上。希望帮到你。本文还有配套的精品资源点击获取