WinForm上传文件到共享文件夹的WNetUseConnection实战

简介：面向C# Winform开发者的文件上传示例项目，解决局域网内将本地文件传输至服务器共享文件夹的问题。资源完整覆盖文件选择、网络凭据连接、IO流读写、进度条显示、异常处理及安全校验等环节，适合正在学习C#网络编程或需要快速实现文件共享上传功能的中初级开发者参考。压缩包共23个文件，以C#源码（cs）为主，其中6个cs文件承载核心逻辑；另含可直接运行的exe、调试符号pdb、界面资源resx、工程配置文件sln/csproj及应用程序清单，整体仅36KB，精简无冗余，便于逐文件研读。目前已有1421人学习下载，项目基于VS2010编译，核心Form1.cs中演示了OpenFileDialog选择文件、NetworkCredential配置访问凭据、FileStream/NetworkStream进行数据传输以及BackgroundWorker实现异步进度更新的配合用法。通过分析源码可掌握Winform中操作网络共享目录的关键技巧，理解UncPath路径格式与权限校验细节，并借鉴企业场景下的上传流程设计，对C#入门进阶均有实际帮助。 WinForm 程序上传文件到共享文件夹，这个需求在内网办公环境里其实特别常见。不管是做 OA 的附件归档、进销存系统的单据图片上传，还是把客户端生成的报表自动丢到文件服务器上，本质上都是同一件事：把用户在 Windows 客户端上选中的文件，安全可靠地写进局域网里那台开了共享的机器里。

很多人第一反应是“这不就 File.Copy 一行代码的事吗”，真做起来才发现坑不少——网络路径访问不了、弹出密码框、文件被占用、上传大文件界面卡死，这些问题几乎每个人都会碰到。这篇就把我从需求分析到完整实现的思路、代码和踩坑记录都整理出来，给正准备做这个功能或者已经踩坑的朋友一份能直接照着用的参考。

1. 先想清楚：共享目录上传有几条路可以走

1.1 三种主流方案的适用场景对比

WinForm 访问共享文件夹，底层无非就是走 Windows 的 SMB 协议，但代码层面可以有不同的写法。我按实际工程里的使用频率排个序：

• 直接使用 UNC 路径读写。比如\\192.168.1.10\files\xxx.pdf，配合File.Copy、FileStream这些常规 IO 类直接操作。前提是当前 Windows 登录用户本来就有共享目录的权限，或者系统已经保存过凭据。
• 先用WNetUseConnection这类 API 建立网络连接，再走 UNC 路径。程序里自己管理账号密码，适合客户端用户没有目标机器账号、需要统一用服务账号上传的场景。
• 映射网络驱动器，把共享目录变成Z:盘再读写。操作上最简单，但映射状态是全局的，容易和用户手动映射的其他盘符冲突，多用户环境里还可能出现“明明映射了但程序读不到”的鬼问题。

这三种方案各有各的适用面。如果系统登录账号和共享目录权限是打通的，方案一最省事。如果是那种几十上百个客户端要用同一个“上传专用账号”写文件的场景，方案二最稳。方案三我一般只在快速验证时用，真正交付的程序很少这么干——盘符冲突和凭据残留会让你后期维护得很痛苦。

1.2 为什么我强烈建议用“账号密码可配置”的方式

实际项目里，共享目录的管理员很可能不会为每个客户端用户单独开账号，而是开一个通用的上传账号，比如uploader。这种情况下，客户端程序就得自己带着账号密码去建立连接。

我做过的一个案例是给门店客户端上传销售小票图片，公司文件服务器上只开了一个store_upload账号，密码定期轮换。这时候如果写死账号在代码里，每次改密码都要重新发版，非常被动。正确的做法是把共享路径、账号、密码都放到配置文件里，App.config或者单独的upload.config都行，这样运维改了密码只要远程改配置文件，程序重启后自动生效。

还有一个容易忽略的点：用户名可以写成IP 地址\用户名或者机器名\用户名的形式，也可以直接用用户名。跨域场景下建议显式指定域名或机器名，否则系统可能用当前登录域去尝试认证，导致明明密码对了还是报错。

2. 核心实现：程序内完成共享目录身份认证

2.1 用 WNetUseConnection 建立网络连接的关键代码

如果你的程序需要绕过当前用户、用指定账号访问共享目录，最常用的做法是调用mpr.dll里的WNetUseConnection函数。这个函数的作用就是给当前进程建立一条到共享资源的网络连接，连接建立之后，再用普通的 IO 类去操作 UNC 路径就可以了。

先上 P/Invoke 声明部分：

using System; using System.ComponentModel; using System.Runtime.InteropServices; public class NetworkShareConnector { [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)] public 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.Auto)] public static extern int WNetUseConnection( IntPtr hwndOwner, ref NETRESOURCE lpNetResource, string lpPassword, string lpUserID, int dwFlags, string lpAccessName, string lpBufferSize, string lpResult); [DllImport("mpr.dll", CharSet = CharSet.Auto)] public static extern int WNetCancelConnection2( string lpName, int dwFlags, bool fForce); public const int CONNECT_INTERACTIVE = 0x00000008; public const int CONNECT_PROMPT = 0x00000010; public const int CONNECT_UPDATE_PROFILE = 0x00000001; public static string Connect(string remotePath, string userName, string password) { NETRESOURCE netRes = new NETRESOURCE(); netRes.dwType = 1; // RESOURCETYPE_DISK netRes.lpRemoteName = remotePath; int result = WNetUseConnection( IntPtr.Zero, ref netRes, password, userName, 0, null, null, null); if (result != 0) { throw new Win32Exception(result); } return remotePath; } public static void Disconnect(string remotePath) { WNetCancelConnection2(remotePath, 0, true); } }

注意dwType要设置为 1，也就是磁盘资源类型。lpRemoteName就是共享路径，比如\\192.168.1.10\share。调用成功时返回 0（NO_ERROR），其他返回值需要转成Win32Exception才能看到具体错误信息。

2.2 为什么不用“命令行 net use” 来实现

很多人会问：直接Process.Start("net use ...")不也能建立连接吗？确实可以，而且网上不少老代码就是这么干的，但我不推荐在正式项目里用这种方式，原因有三个：

• net use建立的连接是全局的，会影响当前用户所有进程。程序退出后连接可能还留着，安全上不可控。
• 解析命令行输出很麻烦，返回码和错误信息不好统一处理，代码容易写得又长又脆。
• 杀毒软件和系统策略对cmd.exe拉起网络命令的行为敏感，容易出现误拦截。

WNetUseConnection是 Windows 提供的标准网络 API，调用时传入IntPtr.Zero作为窗口句柄，不会弹出任何 UI 对话框，属于静默认证，体验上干净得多。而且断开连接时用WNetCancelConnection2可以按需释放，不会在客户端留下残留连接。

2.3 连接状态和三段式空路径判断

调用WNetUseConnection之前，建议先判断目标共享是否已经可访问，避免重复建立连接抛出“本地设备名已在使用中”的错误。可以在建立连接前先尝试用Directory.Exists(remotePath)探测，如果能直接访问，说明当前会话已经有权限，就不需要再调 API 了。

3. 完整实操：从文件选择到上传进度的落地代码

3.1 界面与上传逻辑的职责划分

WinForm 里有一个原则必须记住：网络 IO 绝对不能放在 UI 线程里同步执行。别看本地复制文件很快，走网络共享时如果文件稍大或者网络波动，界面会直接卡死，用户体验极差，系统还会弹“白屏无响应”的提示。

所以界面聚焦在三件事：选文件、展示进度、显示结果。上传逻辑放到异步方法里执行。我用的 .NET 版本不同，写法略有差别，但思路一致——用async/await配合Task.Run：

private async void btnUpload_Click(object sender, EventArgs e) { if (string.IsNullOrEmpty(txtSourceFile.Text)) { MessageBox.Show("请先选择要上传的文件"); return; } btnUpload.Enabled = false; try { bool success = await Task.Run(() => UploadFileToShare( txtSourceFile.Text, config.SharePath, config.UserName, config.Password)); if (success) { MessageBox.Show("上传成功"); } } catch (Exception ex) { MessageBox.Show("上传失败：" + ex.Message); } finally { btnUpload.Enabled = true; } }

用Task.Run把整个上传过程（包括建立连接、拷贝文件、断开连接）丢到线程池线程去执行，UI 线程只做状态提示，界面就不会卡了。

3.2 上传方法的具体实现

上传方法里要做几件事：检查共享是否可访问、建立连接、检查目标目录是否存在、避免重名、执行文件写入、处理异常、断开连接。完整代码如下：

public bool UploadFileToShare(string localFilePath, string sharePath, string userName, string password) { if (!File.Exists(localFilePath)) { throw new FileNotFoundException("本地文件不存在", localFilePath); } bool needDisconnect = false; try { // 先探测可访问性 if (!Directory.Exists(sharePath)) { // 尝试建立连接 NetworkShareConnector.Connect(sharePath, userName, password); needDisconnect = true; } // 确保目标目录存在 if (!Directory.Exists(sharePath)) { throw new DirectoryNotFoundException("无法访问共享目录：" + sharePath); } string fileName = Path.GetFileName(localFilePath); string targetPath = Path.Combine(sharePath, fileName); // 处理同名文件：加时间戳 if (File.Exists(targetPath)) { string nameOnly = Path.GetFileNameWithoutExtension(fileName); string ext = Path.GetExtension(fileName); targetPath = Path.Combine(sharePath, $"{nameOnly}_{DateTime.Now:yyyyMMdd_HHmmss}{ext}"); } // 执行上传 File.Copy(localFilePath, targetPath); LogHelper.WriteLog($"文件上传成功：{localFilePath} -> {targetPath}"); return true; } finally { if (needDisconnect) { try { NetworkShareConnector.Disconnect(sharePath); } catch { // 断开失败不影响主流程，忽略 } } } }

这里有几个细节值得注意：

• Directory.Exists返回false不一定代表目录不存在，也可能是当前会话没有权限访问。所以探测失败后要尝试连接，再探测一次。
• 同文件名冲突是共享上传最常见的坑。客户端用户不知道共享目录里已经有什么文件，直接覆盖可能会导致别的同事刚传的资料被顶掉。加时间戳是最稳妥的做法，成本最低。
• 上传成功后建议写本地日志。文件传丢了、传错了，没有日志排查起来会非常痛苦。

3.3 上传进度条的实现细节

如果你要显示上传进度，就不能用简单的File.Copy了，因为File.Copy不提供进度回调。这时候需要手动用流来复制，并计算已读字节数占总字节数的比例：

public void CopyFileWithProgress(string sourcePath, string targetPath, IProgress<int> progress) { byte[] buffer = new byte[81920]; // 80KB 缓冲区 long totalBytes = new FileInfo(sourcePath).Length; long readBytes = 0; using (FileStream source = new FileStream(sourcePath, FileMode.Open, FileAccess.Read)) using (FileStream target = new FileStream(targetPath, FileMode.Create, FileAccess.Write)) { int bytesRead; while ((bytesRead = source.Read(buffer, 0, buffer.Length)) > 0) { target.Write(buffer, 0, bytesRead); readBytes += bytesRead; int percent = (int)((double)readBytes / totalBytes * 100); progress.Report(percent); } target.Flush(); } }

IProgress<int>是 .NET 里专门用来在线程池和 UI 线程之间传递进度的机制，内部会帮我们做线程切换，不需要手动Invoke。在界面上实例化时直接传入new Progress<int>(p => progressBar.Value = p)就行。

缓冲区大小我一般用 80KB，这是网上流传的“黄金体积”，实测在大多数网络环境下吞吐比较均衡。太小了Read调用太频繁，太大了反而占用内存。你也可以根据自己的网络情况调，单位是字节。

4. 高频坑位盘点：共享上传的翻车现场实录

4.1 “你不能访问此共享文件夹，因为你组织的安全策略阻止未经身份验证的来宾访问”

这个报错在 Win10 / Win11 访问老共享时极其常见。它的根源是微软默认关闭了不安全的来宾登录，而很多老设备的共享开启的是“来宾”模式。程序里无论传什么账号密码都不好使，因为对方只允许来宾会话。

解决方法在客户端，通常两个：在共享服务器上启用“来宾共享”并设置共享权限包含 Everyone；或者在访问端开启“启用不安全来宾登录”。前一种是改服务端，适合你控制服务器的情况；后一种需要在组策略或注册表里改，注册表项是：

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters AllowInsecureGuestAuth = 1 (DWORD)

但我要提醒一句：随便开启不安全来宾登录在真实办公网络里是有安全风险的，只建议在确定网络环境可信、且只能访问内网老设备时的场景下用。从代码层面能做的，就是捕获到这类错误时，给出明确的中文提示，别让用户看到一堆十六进制错误码。

4.2 “找不到网络路径”是什么原因

这个报错基本就是“连不上对方机器”，和账号密码无关。排查顺序我一般这样走：

• 用ping或直接\\IP测试看能不能通，不通就先查网段、防火墙。
• Windows 共享依赖SMB协议，旧机器默认 SMB1.0，Win10/11 默认可能没启用。如果是 Win7 时代的共享服务器，需要到“启用或关闭 Windows 功能”里勾选 SMB 1.0/CIFS 客户端。
• 网络发现和文件共享功能是否开启。有些精简版系统会把“网络发现”关掉，会直接导致无法访问。
• 防火墙拦截了 445 端口。办公网络里，445 端口被安全软件拦截的情况也有。

4.3 为什么 winform 程序里能访问，手动双击反而访问不了

这个看似诡异，其实是凭据作用域的问题。程序里用WNetUseConnection建立的连接是进程级的，在当前进程内有效。用户在资源管理器里手动访问共享时，用的是交互式会话的凭据，这两者互不相通。

所以如果程序在运行时已经连上了共享，用户可以正常运行；但如果测试人员一边开着资源管理器去访问同一个路径，可能会遇到“你没有权限访问”之类的问题，别慌，这不是程序 bug，而是两套会话体系不一样。验证程序功能时让用户直接看上传结果即可，不要同时手动去访问同一个路径，容易造成误导。

4.4 上传大文件时界面卡死和超时问题

大文件走网络共享，除了 UI 卡死，还可能遇到超时。SMB 会话如果空闲太久或者传输过程中网络抖动，连接会断。处理办法主要有这么几点：

• 核心就是异步 + 流式写入，不要一次性把整个文件读进内存，改用流分块读写。
• 为网络操作设置合理的超时时间，可以用async方式配合CancellationTokenSource做取消。
• 大文件（比如超过几百 MB）建议加个断点续传机制。SMB 协议本身不支持简单断点续传，但可以自己记录已传字节数，下次接着传。不过这个复杂度较高，一般内网传输稳定性还可以，不一定要做。
• 实在卡在超大文件上，可以考虑先用File.Copy到本机再异步上传的缓写策略，但本质优化空间有限。

4.5 跨系统访问：银河麒麟等非 Windows 环境的共享

热词里有“两个电脑共享文件夹 windows 连银河麒麟”，其实就是 Windows 客户端访问 Linux/麒麟系统搭建的 Samba 共享。和 Windows 对 Windows 的差异主要体现在认证和权限上。

• Samba 共享如果开了“仅来宾”或者账号映射有问题，就会报错。
• Samba 本身也有协议版本设置的讲究，新版本 Samba 默认只允许 SMB2/3，如果 Windows 只走 SMB1 就访问不了。
• 代码层面不用改，仍然是 UNC 路径 +WNetUseConnection的方式，只是遇到错误时错误码含义可能需要结合服务端的 Samba 日志一起看。

5. 工程落地：配置文件、日志和异常处理一个都不能少

5.1 把共享配置放到配置文件里

账号密码写死在代码里是最傻的运维噩梦。至少放到App.config里，用ConfigurationManager读，这样运维改密码不用重新编译：

<appSettings> <add key="SharePath" value="\\192.168.1.10\upload" /> <add key="ShareUser" value="store_upload" /> <add key="SharePassword" value="密码在这里" /> </appSettings>

如果安全要求再高一点，密码可以加密存储，或者用 Windows 凭据管理器（Credential Manager）来保存，程序通过CredRead读取。不过大多数内网工具类程序做到配置文件加密这一步已经完全够用了。

5.2 日志是排查问题的眼睛

共享上传出问题时，最痛苦的是看不到任何线索。我强烈建议不管项目多小，都加上一个简单的文件日志。不需要引入很重的日志框架，自己写一个静态类几十行就够了，记录关键节点：

• 开始上传时间、源文件路径。
• 建立连接是否成功、错误码。
• 文件名是否有重名冲突、最终目标路径。
• 上传完成或失败的异常信息。

实际排查问题时，这几点信息能帮你快速确认问题是出在网络层、认证层还是文件写入层。

5.3 错误提示要“说人话”

WinForm 程序面对的用户大部分不是技术人员。把Win32Exception的错误码直接弹给用户，用户看不懂，只会觉得“这个软件坏了”。建议做一层错误翻译，常见错误码映射成友好提示：

这样即使用户报错，反馈上来的信息也有意义，你远程指导时能少费很多口舌。

6. 我把这个功能做成通用组件的经验

做过的共享上传功能多了之后，我习惯把代码整理成一个独立的上传组件，不外乎一个类、一个配置节、两个方法。核心逻辑不变，只是把可变的参数都抽出来，这样每个新项目接入时只需要配置一下就能用。

还有一个小技巧：如果目标共享路径特别多，比如要同时上传到多个共享目录，尽量循环复用同一个连接，不要每个文件都去连一次、断一次。连接和断开是有开销的，批量上传场景下会明显变慢。正确做法是先建立连接，然后整个批量过程都复用这个会话，最后统一断开。

最后再分享一个我踩过的坑：程序里调用WNetCancelConnection2强行断开共享时，如果当时有其他程序正在使用这个共享路径，有可能会导致那个程序报错。所以断开操作不要放在上传成功后的第一时间执行，可以给用户留一个“上传会话保持”的选项，或者至少等几秒再断开，避免影响同一台机器上的其他操作。用fForce参数设置为false，别强制断开，让系统自然释放会安全得多。

本文还有配套的精品资源，点击获取