度條實(shí)例：C# FtpWebRequest真實(shí)進(jìn)度反饋與斷點(diǎn)續(xù)傳)
簡介面向需要在桌面客戶端中實(shí)現(xiàn)FTP上傳和實(shí)時(shí)進(jìn)度反饋的.NET開發(fā)者這份C#實(shí)例完整演示了基于FTP協(xié)議分塊傳輸文件、按已上傳與總字節(jié)數(shù)比例計(jì)算進(jìn)度的實(shí)現(xiàn)方式適合C#入門學(xué)習(xí)及需要快速集成的項(xiàng)目參考。項(xiàng)目采用WinForms窗體搭建覆蓋建立連接、身份認(rèn)證、工作目錄切換、調(diào)用STOR命令上傳及回調(diào)更新進(jìn)度條等關(guān)鍵環(huán)節(jié)并在UpLoadFiles模塊中集中了上傳與進(jìn)度計(jì)算邏輯便于提取復(fù)用。資源包共35個(gè)文件壓縮后僅78KB核心為12個(gè)cs源文件輔以resources/resx界面資源、sln/csproj/config配置以及exe等編譯產(chǎn)物目錄結(jié)構(gòu)清晰可直接按窗體或工具類模塊查閱。已有868人學(xué)習(xí)下載。其中UpLoadFiles模塊里的上傳進(jìn)度計(jì)算、異常處理與重試思路以及對網(wǎng)絡(luò)延遲、文件大小限制、權(quán)限異常等常見問題的應(yīng)對策略均可遷移到實(shí)際項(xiàng)目中省去底層協(xié)議調(diào)試時(shí)間提升上傳交互體驗(yàn)。1. FTP上傳帶進(jìn)度條一份能真實(shí)反饋傳輸狀態(tài)的完整實(shí)例如果你在找 FTP 上傳帶進(jìn)度條的代碼而不是那種靠 Timer 滾動(dòng)出來的假進(jìn)度——這份實(shí)例可以直接照著做一個(gè)能用的工具。它基于 C# WinForm 實(shí)現(xiàn)用 FtpWebRequest 做協(xié)議層請求BackgroundWorker 做后臺(tái)任務(wù)進(jìn)度條顯示的是真實(shí)寫入的字節(jié)數(shù)傳多少顯示多少失敗就停在原地不會(huì)出現(xiàn)“進(jìn)度到 100% 文件卻沒到”的經(jīng)典假象。適合三類人需要給公司做文件上報(bào)、數(shù)據(jù)分發(fā)工具的開發(fā)者剛接觸 FtpWebRequest 想直接抄代碼的新手以及被假進(jìn)度條坑過、想徹底改掉這個(gè)壞習(xí)慣的運(yùn)維。下文從請求鏈路講起逐步落到可運(yùn)行的完整實(shí)現(xiàn)。提示這份資源是一套可運(yùn)行的 C# WinForm 工程源碼核心功能就一個(gè)——把本地文件通過 FTP 傳到服務(wù)器并且全程顯示真實(shí)進(jìn)度。2. FtpWebRequest 上傳鏈路先看清請求模型和進(jìn)度數(shù)據(jù)從哪來2.1 一次上傳請求的完整生命周期控制連接與數(shù)據(jù)連接的分工FTP 和 HTTP 最大的區(qū)別在于FTP 有兩條獨(dú)立的通道?？刂七B接負(fù)責(zé)傳指令USER、PASS、STOR、QUIT 這些數(shù)據(jù)連接才是真正搬運(yùn)文件字節(jié)內(nèi)容的管道。FtpWebRequest 雖然把這兩條通道封裝成了一個(gè)對象但它底層做的工作并沒有變——理解這一點(diǎn)能幫你省下大量查日志的時(shí)間。一次完整的 FtpWebRequest.UploadFile 請求內(nèi)部大致按這個(gè)順序執(zhí)行建立到服務(wù)器 21 端口的 TCP 控制連接發(fā)送 USER、PASS 完成身份認(rèn)證對應(yīng)的是你設(shè)置的 Credentials根據(jù) UsePassive 屬性決定數(shù)據(jù)通道的建立方式——被動(dòng)模式PASV是客戶端主動(dòng)連接服務(wù)器開放的數(shù)據(jù)端口主動(dòng)模式PORT是服務(wù)器回頭連你的客戶端。公網(wǎng)、內(nèi)網(wǎng)穿透、帶防火墻的環(huán)境基本都推薦被動(dòng)模式發(fā)送 STOR 命令向服務(wù)器聲明“我要上傳這個(gè)文件”文件名就是 URL 里最后一個(gè)路徑段數(shù)據(jù)通道建立后客戶端把文件字節(jié)流寫入 GetRequestStream() 拿到的 Stream寫完后關(guān)閉數(shù)據(jù)連接服務(wù)器返回 226 Transfer complete 確認(rèn)收完如果沒設(shè) KeepAlivefalse控制連接還會(huì)保持一段時(shí)間方便你繼續(xù)發(fā)下一條命令。這套流程能解釋絕大部分上傳問題。你看到請求拋異常先按返回碼定位530 是認(rèn)證失敗550 是文件操作不合法425/426 是數(shù)據(jù)通道建立失敗。我見過不少人把這幾類錯(cuò)誤混為一談?chuàng)Q了半天服務(wù)器配置最后發(fā)現(xiàn)只是賬號(hào)密碼不對。選被動(dòng)還是主動(dòng)在真實(shí)環(huán)境里經(jīng)常是個(gè)玄學(xué)問題。公司出網(wǎng)防火墻一般只放行出站連接主動(dòng)模式的 PORT 命令要求服務(wù)器回連你客戶端的隨機(jī)端口大概率被防火墻攔掉。所以現(xiàn)代 FTP 客戶端默認(rèn)都是被動(dòng)模式。但被動(dòng)模式下服務(wù)器開放的臨時(shí)數(shù)據(jù)端口范圍如果被服務(wù)端防火墻限制得很窄又會(huì)出現(xiàn)控制連接秒開、數(shù)據(jù)通道超時(shí)的怪象。這種問題排查起來最像玄學(xué)——換一個(gè)端口范圍就好了?？傊瓼tpWebRequest 里設(shè) UsePassivetrue 的同時(shí)最好讓 FTP 服務(wù)端把被動(dòng)端口范圍放寬并固定下來日志里看到 Entering Passive Mode 時(shí)能對得上端口區(qū)間就知道該去哪里查了。2.2 進(jìn)度數(shù)據(jù)從哪來Stream 層的字節(jié)計(jì)數(shù)是唯一可靠來源進(jìn)度條的本質(zhì)是“已上傳字節(jié)數(shù)”除以“總字節(jié)數(shù)”。想拿到這個(gè)可靠數(shù)據(jù)必須在文件字節(jié)流這一層數(shù)數(shù)——也就是你自己負(fù)責(zé)讀本地文件再寫入請求流每一步記錄累加值。很多圖省事的人直接調(diào) UploadFile 這類一鍵方法內(nèi)部把整個(gè)文件吞進(jìn)去你拿不到中間狀態(tài)進(jìn)度條就只能靠猜。所以我在這個(gè)工程里刻意把“讀”和“寫”拆開用循環(huán)一塊一塊地搬// 手動(dòng)讀取本地文件寫入FTP請求流每塊記錄一次進(jìn)度 using (FileStream fs File.OpenRead(localPath)) using (Stream requestStream request.GetRequestStream()) { byte[] buffer new byte[64 * 1024]; // 緩沖區(qū)大小64KB int bytesRead; long total 0; while ((bytesRead fs.Read(buffer, 0, buffer.Length)) 0) { requestStream.Write(buffer, 0, bytesRead); total bytesRead; // 這里的total就是真實(shí)進(jìn)度 progress?.Report(total); } }緩沖區(qū)大小是個(gè)折中選擇64KB 內(nèi)存占用小進(jìn)度刷新粒度又足夠平滑。要是設(shè)成 4MB大文件下進(jìn)度條是幾秒一跳的頓挫感設(shè)成 512B網(wǎng)絡(luò)小包暴增服務(wù)器 CPU 也會(huì)被無謂消耗。另一個(gè)關(guān)鍵點(diǎn)是 total 必須在 Write 之后立即累加。這樣即使某次寫失敗進(jìn)度條停留的位置也是真實(shí)已經(jīng)推到網(wǎng)絡(luò)上的位置不會(huì)出現(xiàn)“顯示到了、數(shù)據(jù)沒到”的偏差。還有一個(gè)容易被忽略的細(xì)節(jié)GetRequestStream() 返回的流綁定著 FTP 數(shù)據(jù)通道狀態(tài)不能用 Stream.CopyTo 這類快捷方式。CopyTo 內(nèi)部替你讀了寫、寫了讀但你插不上手?jǐn)?shù)數(shù)。要么拆開循環(huán)自己累加要么給流套一層帶回調(diào)的包裝流。前者代碼直觀后者侵入性好但調(diào)試麻煩。對于一個(gè)小工具來說手動(dòng)循環(huán)最劃算。另外手工循環(huán)還有一個(gè)額外好處天然支持速度統(tǒng)計(jì)。循環(huán)里記錄每次 Write 的耗時(shí)用 bytesRead 除以耗時(shí)就得到實(shí)時(shí)速率。假進(jìn)度方案根本做不了這個(gè)功能因?yàn)樗途W(wǎng)絡(luò)傳輸之間沒有對應(yīng)關(guān)系。2.3 三種進(jìn)度實(shí)現(xiàn)方案對比假進(jìn)度、流計(jì)數(shù)與輪詢?yōu)榱俗屇氵x型時(shí)不用重新踩坑我把常見的三種做法做了個(gè)對比方案原理真實(shí)度適用場景缺點(diǎn)計(jì)時(shí)器假滾動(dòng)Timer 每隔 100ms 給進(jìn)度條 Value 加 1低演示 Demo、臨時(shí)工具和實(shí)際傳輸完全脫節(jié)失敗也照常滾字節(jié)流計(jì)數(shù)循環(huán)讀寫時(shí)累計(jì)實(shí)際字節(jié)數(shù)高生產(chǎn)環(huán)境、大文件、需要精確反饋必須手動(dòng)拆讀和寫代碼稍多服務(wù)器輪詢上傳期間循環(huán)調(diào) GetFileSize 探測中拿不到中間流的封裝 SDK多一次 RTT實(shí)時(shí)性差有額外開銷我只有在兩種情況下用輪詢一是上傳流程被第三方 SDK 封裝死了拿不到中間流二是斷點(diǎn)續(xù)傳時(shí)探測服務(wù)器已有字節(jié)數(shù)。平時(shí)的上傳工具字節(jié)流計(jì)數(shù)是毫無疑問的最優(yōu)解。選型最怕的是過度設(shè)計(jì)。如果只是內(nèi)網(wǎng)傳幾十 KB 的小腳本文件假進(jìn)度其實(shí)無傷大雅用戶不會(huì)盯著進(jìn)度條。但只要文件可能超過 50MB或者要跨公網(wǎng)傳到別人的服務(wù)器就必須用流計(jì)數(shù)。這個(gè)場景下進(jìn)度條承擔(dān)的不只是“好看”它還負(fù)責(zé)讓使用者判斷當(dāng)前網(wǎng)絡(luò)狀態(tài)、決定要不要中斷重傳。一個(gè)假進(jìn)度條在這種場景里就是誤導(dǎo)。還有關(guān)于憑據(jù)的一個(gè)小坑NetworkCredential 的 domain 參數(shù)對標(biāo)準(zhǔn) FTP 沒有意義但在和 Active Directory 集成的 FTP 服務(wù)端比如 IIS FTP上用戶名要寫完整或者賬號(hào)信息字段不能為空。否則會(huì)收到 332 Need account for login 這類不常見的錯(cuò)誤碼大多數(shù)人第一反應(yīng)是查服務(wù)端權(quán)限實(shí)際上只是少填了賬號(hào)字段。3. 動(dòng)手實(shí)現(xiàn)C# WinForm 的 FTP 上傳進(jìn)度條完整代碼3.1 界面布局與后臺(tái)任務(wù)設(shè)計(jì)從觸發(fā)到收尾的完整鏈路界面只需要三個(gè)控件一個(gè) ProgressBar 顯示進(jìn)度一個(gè) Label 顯示當(dāng)前狀態(tài)一個(gè) Button 觸發(fā)上傳。要支持取消就再加一個(gè)取消按鈕?？丶g的協(xié)作方式點(diǎn)擊上傳按鈕后不能直接在主線程里執(zhí)行上傳邏輯——網(wǎng)絡(luò)讀取的阻塞調(diào)用會(huì)讓整個(gè)窗體失去響應(yīng)表現(xiàn)為白屏和拖動(dòng)卡頓。正確做法是啟動(dòng) BackgroundWorker 把上傳邏輯丟到后臺(tái)線程UI 只通過事件接收進(jìn)度并更新控件。這種做法跟前端里用 Web Worker 上傳大文件是一個(gè)思路耗時(shí) IO 全部移出主線程主線程只負(fù)責(zé)渲染。WinForm 的 BackgroundWorker 就是這個(gè)角色的封裝它內(nèi)部通過 SynchronizationContext 把進(jìn)度事件封送到 UI 線程所以你在 ProgressChanged 里更新進(jìn)度條不需要寫任何 Invoke 代碼。界面設(shè)計(jì)上要留意一個(gè)原則進(jìn)度條控件本身只管顯示不要在里面塞業(yè)務(wù)邏輯。很多新手把文件大小計(jì)算、網(wǎng)速估算全塞進(jìn) ProgressChanged 回調(diào)結(jié)果 UI 線程被這些雜事拖住進(jìn)度條反而卡頓。把上傳前就確定的值文件總長度提前存字段進(jìn)度回調(diào)里只做兩件事——更新 Value、更新文案。3.2 核心上傳方法帶真實(shí)進(jìn)度計(jì)的 FtpWebRequest 封裝下面的方法建議直接復(fù)制到公共類留出進(jìn)度回調(diào)和取消檢查的接口WinForm、控制臺(tái)、Windows 服務(wù)都能復(fù)用// 帶真實(shí)進(jìn)度回傳的FTP上傳方法 // onProgress: 已上傳字節(jié)數(shù)回調(diào) // checkCancel: 返回true時(shí)終止上傳 public void UploadWithProgress( string localFilePath, string ftpUrl, string userName, string password, Actionlong onProgress, Funcbool checkCancel) { using (FileStream fs File.OpenRead(localFilePath)) { long fileLength fs.Length; FtpWebRequest request (FtpWebRequest)WebRequest.Create(ftpUrl); request.Method WebRequestMethods.Ftp.UploadFile; request.Credentials new NetworkCredential(userName, password); request.UseBinary true; // 二進(jìn)制傳輸防止字節(jié)被改寫 request.UsePassive true; // 被動(dòng)模式繞開防火墻限制 request.KeepAlive false; // 單一文件傳完即關(guān)閉連接 // 關(guān)鍵告訴服務(wù)器文件總長度否則無法判斷傳輸終態(tài) request.ContentLength fileLength; using (Stream requestStream request.GetRequestStream()) { byte[] buffer new byte[64 * 1024]; // 64KB緩沖區(qū) int bytesRead; long totalBytesWritten 0; while ((bytesRead fs.Read(buffer, 0, buffer.Length)) 0) { // 每次寫前檢查取消標(biāo)記協(xié)作式取消 if (checkCancel ! null checkCancel()) { throw new OperationCanceledException(用戶取消上傳); } requestStream.Write(buffer, 0, bytesRead); totalBytesWritten bytesRead; // 上報(bào)真實(shí)字節(jié)數(shù)給UI層 onProgress?.Invoke(totalBytesWritten); } // 沖刷緩沖避免最后一小塊數(shù)據(jù)滯留本地 requestStream.Flush(); } // 必須拿到服務(wù)器確認(rèn)響應(yīng)才算真正完成 using (FtpWebResponse response (FtpWebResponse)request.GetResponse()) { if (response.StatusCode ! FtpStatusCode.ClosingData) { throw new Exception($服務(wù)器返回異常: {response.StatusCode}); } } } }四個(gè)容易忽略的配置這里一并說清。ContentLength 不設(shè)置或設(shè)錯(cuò)服務(wù)器在數(shù)據(jù)通道關(guān)閉時(shí)可能用 451 之類的錯(cuò)誤碼拒絕文件或者一直等數(shù)據(jù)直到超時(shí)。FtpWebRequest 依賴它判斷數(shù)據(jù)流的邊界所以務(wù)必從 FileStream.Length 取真實(shí)字節(jié)數(shù)。UseBinary 決定傳輸模式。對壓縮包、圖片、PDF 這類二進(jìn)制文件如果誤用 ASCII 模式0x0A 單字節(jié)換行符會(huì)被改寫成 0x0D 0x0A 雙字節(jié)文件當(dāng)場損壞。文本文件也建議直接用二進(jìn)制模式服務(wù)器不做任何轉(zhuǎn)換兩邊字節(jié)完全一致。KeepAlivefalse 的意義在于單個(gè)文件傳完就斷開控制連接服務(wù)器端不會(huì)因?yàn)檫B接緩存讓文件句柄遲遲不釋放。循環(huán)傳多個(gè)文件時(shí)反過來KeepAlivetrue 能復(fù)用連接節(jié)省握手開銷。最后是 Flush。requestStream 內(nèi)部有緩沖不 Flush 直接 Close某些實(shí)現(xiàn)會(huì)先關(guān)閉連接再倒緩存導(dǎo)致最后一批數(shù)據(jù)還沒到服務(wù)器就斷了。寫完循環(huán)后、關(guān)閉請求流前主動(dòng) Flush是避免“進(jìn)度條 99% 卡住”的關(guān)鍵動(dòng)作。3.3 跨線程更新進(jìn)度條與狀態(tài)欄BackgroundWorker 的標(biāo)準(zhǔn)連接方式核心方法寫完接下來掛到 UI 上。這里用 BackgroundWorker 而不是 async/await是為了讓沒升級(jí)到 .NET 4.5 的舊工程也能直接抄// 點(diǎn)擊上傳按鈕后啟動(dòng)后臺(tái)任務(wù) private void btnUpload_Click(object sender, EventArgs e) { OpenFileDialog dlg new OpenFileDialog(); if (dlg.ShowDialog() ! DialogResult.OK) return; string localPath dlg.FileName; string uploadUrl ftp://192.168.1.100/share/ Path.GetFileName(localPath); long totalLength new FileInfo(localPath).Length; // 提前緩存避免回調(diào)里反復(fù)IO BackgroundWorker worker new BackgroundWorker(); worker.WorkerReportsProgress true; worker.WorkerSupportsCancellation true; // 后臺(tái)執(zhí)行上傳邏輯 worker.DoWork (s, e2) { try { UploadWithProgress( localPath, uploadUrl, ftpuser, ftppass, // 每次回調(diào)都報(bào)告百分比UserState傳出字節(jié)數(shù) (bytes) { int percent (int)(bytes * 100 / totalLength); worker.ReportProgress(percent, bytes); }, // 取消檢查直接讀標(biāo)志位 () worker.CancellationPending ); } catch (OperationCanceledException) { e2.Cancel true; // 用戶取消不按失敗處理 } catch (Exception ex) { e2.Result ex; // 異常帶回UI線程 } }; // 更新進(jìn)度條與狀態(tài)欄 worker.ProgressChanged (s, e2) { progressBar.Value e2.ProgressPercentage; long bytes (long)e2.UserState; lblStatus.Text $已上傳 {FormatFileSize(bytes)} / {FormatFileSize(totalLength)}; }; // 上傳完成后的收尾 worker.RunWorkerCompleted (s, e2) { if (e2.Cancelled) { lblStatus.Text 已取消上傳; } else if (e2.Result is Exception ex) { lblStatus.Text 上傳失敗 ex.Message; } else { lblStatus.Text 上傳完成; } progressBar.Value 0; }; worker.RunWorkerAsync(); }進(jìn)度更新這個(gè)環(huán)節(jié)最常報(bào)的錯(cuò)是“跨線程操作無效”。DoWork 跑在后臺(tái)線程直接操作 progressBar 必然拋 InvalidOperationException。BackgroundWorker 的 ReportProgress 機(jī)制會(huì)自動(dòng)封送到 UI 線程所以 ProgressChanged 里不需要任何 Invoke 代碼。這條規(guī)則不僅適用進(jìn)度條狀態(tài)欄、列表控件都是同樣的處理方式。取消按鈕的配合也很簡單取消按鈕里調(diào) worker.CancelAsync()然后立刻把取消按鈕禁用、上傳按鈕恢復(fù)防止重復(fù)點(diǎn)擊。CancelAsync 不會(huì)中斷正在執(zhí)行的代碼它只是把 CancellationPending 置為 true循環(huán)必須主動(dòng)檢查這個(gè)標(biāo)志才能退出。這就是協(xié)作式取消在 BackgroundWorker 里體現(xiàn)得最典型。3.4 關(guān)鍵參數(shù)清單按生產(chǎn)標(biāo)準(zhǔn)一次設(shè)對參數(shù)推薦值說明UseBinarytrue二進(jìn)制傳輸防止換行符被改寫UsePassivetrue被動(dòng)模式減少防火墻影響KeepAlivefalse單文件上傳后斷開控制連接ContentLength本地文件長度必須設(shè)置否則服務(wù)器無法確認(rèn)文件邊界Timeout30000ms建立連接和發(fā)送命令的超時(shí)ReadWriteTimeout60000ms單個(gè)讀寫操作的最大耗時(shí)緩沖區(qū)64KB內(nèi)存與網(wǎng)絡(luò)包數(shù)量的折中Timeout 和 ReadWriteTimeout 是兩回事這點(diǎn)很多人栽過。Timeout 管連接建立和命令收發(fā)ReadWriteTimeout 管數(shù)據(jù)流的單次讀寫。弱網(wǎng)下傳大文件默認(rèn) 30 秒的 ReadWriteTimeout 可能不夠網(wǎng)絡(luò)抖動(dòng)一下讀寫就中斷了。按文件大小和帶寬估算留出余量再設(shè)。另外把 FTP 當(dāng)內(nèi)部文件共享用跨網(wǎng)段比 SMB 省心是常見做法但一定要給共享目錄配專用賬號(hào)別用匿名登錄。匿名賬號(hào)在不少服務(wù)端被設(shè)置為只讀上傳時(shí)總是神秘失敗日志看不出來最后發(fā)現(xiàn)是權(quán)限位不對。4. 避坑與常見問題進(jìn)度條翻車的五個(gè)真實(shí)場景4.1 現(xiàn)象進(jìn)度卡在 99% 不動(dòng)最后拋超時(shí)異常原因請求流內(nèi)部的緩沖區(qū)沒有沖刷干凈數(shù)據(jù)還滯留在本地就關(guān)閉了連接服務(wù)器等不到最后一個(gè)數(shù)據(jù)塊超時(shí)斷開。解決關(guān)流之前顯式調(diào)用 requestStream.Flush()。同時(shí)檢查循環(huán)里是否把 Close 寫在了所有 Write 完成之前。我最初寫的版本就是 Write 完直接 Close導(dǎo)致最后一塊數(shù)據(jù)總是丟。從那以后我關(guān)閉任何網(wǎng)絡(luò)流的順序都固定為寫完 → Flush → Close一步不亂。4.2 現(xiàn)象進(jìn)度條到 100%服務(wù)器上卻找不到文件原因最常見的有兩個(gè)。一是 UseBinary 沒設(shè) true二進(jìn)制文件被傳輸模式改寫字節(jié)服務(wù)端校驗(yàn)失敗后丟棄二是請求流寫完就關(guān)沒等 GetResponse() 拿到 226 確認(rèn)。解決使用二進(jìn)制模式并保留到 GetResponse() 返回 226 才算真正結(jié)束。進(jìn)度到 100% 只代表本地流寫完不等于服務(wù)器確認(rèn)收完。如果你用第 3 章的封裝這段邏輯已經(jīng)包含在內(nèi)不要手動(dòng)提前釋放 request。4.3 現(xiàn)象大文件一上傳界面就假死拖動(dòng)窗口都費(fèi)勁原因上傳邏輯跑在 UI 線程FtpWebRequest 同步方法讀取網(wǎng)絡(luò)流時(shí)阻塞線程窗口消息全部排隊(duì)界面自然無響應(yīng)。解決把上傳丟到 BackgroundWorker 或 Task.Run 里。如果已經(jīng)用了后臺(tái)線程但還是卡檢查 ProgressChanged 回調(diào)里有沒有耗時(shí)操作——有人習(xí)慣在回調(diào)里 new FileInfo(localPath).Length 重新取文件大小文件一大這步磁盤 IO 就能拖慢 UI。文件總長度應(yīng)在點(diǎn)擊上傳時(shí)就緩存好回調(diào)里只做控件賦值。4.4 現(xiàn)象上傳中斷后服務(wù)器殘留半截文件下次繼續(xù)傳也不完整原因取消或斷網(wǎng)時(shí)服務(wù)端已經(jīng)創(chuàng)建了目標(biāo)文件并寫入了部分字節(jié)但因?yàn)闆]收到結(jié)束標(biāo)志文件被留在異常狀態(tài)。解決在取消和異常處理中主動(dòng)發(fā) DELE 命令刪除殘留文件或者實(shí)現(xiàn)斷點(diǎn)續(xù)傳。第 5 章會(huì)給出 DELE 清理的完整代碼。這里先記住一個(gè)原則取消上傳不只是中斷本地循環(huán)還要向服務(wù)器聲明“我剛才那個(gè)文件不算數(shù)”否則你會(huì)在服務(wù)器上留一堆垃圾文件。4.5 現(xiàn)象返回 530 Authentication failed賬號(hào)密碼看著沒錯(cuò)原因很多 FTP 服務(wù)器開了賬號(hào)鎖定策略密碼連續(xù)錯(cuò)幾次會(huì)鎖一段時(shí)間或者服務(wù)端要求顯式 TLS。還有一種情況賬號(hào)是弱口令被安全掃描器探測并鎖定了你在客戶端這邊看賬號(hào)密碼完全沒問題。解決先登錄 FTP 服務(wù)端管理界面看賬號(hào)狀態(tài)再確認(rèn)是否強(qiáng)制 FTPS。FtpWebRequest 里設(shè)置 EnableSsl true 即可走加密通道。生產(chǎn)環(huán)境一定單獨(dú)建低權(quán)限專用賬號(hào)別用 root 或管理員級(jí)別的賬號(hào)連應(yīng)用順手把 FTP 弱口令這個(gè)隱患也堵上。5. 進(jìn)階取消與斷點(diǎn)續(xù)傳——把進(jìn)度條升級(jí)成可中斷任務(wù)5.1 協(xié)作式取消的完整閉環(huán)中斷循環(huán)、清理殘留、通知上層第 3 章用的 BackgroundWorker.CancellationPending 是標(biāo)準(zhǔn)的協(xié)作式取消。如果你的代碼要復(fù)用進(jìn) Windows Service 或命令行工具更通用的做法是注入 CancellationToken。無論哪種方式核心都在于“循環(huán)內(nèi)部自己檢查標(biāo)記、自己退出”。退出之后的清理動(dòng)作往往被忽略。中斷上傳時(shí)服務(wù)器上已經(jīng)生成了一個(gè)不完整的文件正確順序是先拋出 OperationCanceledException 退出循環(huán)然后在 catch 塊里發(fā)一條 DELE 命令刪除目標(biāo)文件最后再重新拋出讓上層感知// 取消上傳時(shí)清理服務(wù)器殘留的半截文件 catch (OperationCanceledException) { try { FtpWebRequest delRequest (FtpWebRequest)WebRequest.Create(ftpUrl); delRequest.Method WebRequestMethods.Ftp.DeleteFile; delRequest.Credentials new NetworkCredential(userName, password); using (FtpWebResponse delResponse (FtpWebResponse)delRequest.GetResponse()) { // 刪除成功或返回550文件不存在都視為清理完成 } } catch { // 清理失敗不阻斷主流程 } throw; }DELE 命令走的是控制連接不涉及數(shù)據(jù)通道所以即使數(shù)據(jù)流已經(jīng)中斷這條命令大概率還能成功。如果服務(wù)端本身有殘留文件自動(dòng)清理策略這一步可以省略但作為應(yīng)用層兜底做了永遠(yuǎn)比不做好。這里的核心思想是取消操作要保證“不留臟數(shù)據(jù)”這比“快速退出”更重要。5.2 斷點(diǎn)續(xù)傳ContentOffset 與服務(wù)器已有文件大小的配合斷點(diǎn)續(xù)傳的底層是 FTP 的 REST 命令客戶端先發(fā)REST 1024再發(fā) STOR服務(wù)端就從第 1024 個(gè)字節(jié)開始繼續(xù)寫入。FtpWebRequest 里對應(yīng)的是 ContentOffset 屬性設(shè)置后框架會(huì)自動(dòng)在 STOR 前發(fā)送 REST 命令。實(shí)現(xiàn)分兩步。第一步探測服務(wù)器上已有的文件大小// 探測服務(wù)器已存在文件的大小用于斷點(diǎn)續(xù)傳 private long GetRemoteFileSize(string ftpUrl, string userName, string password) { FtpWebRequest req (FtpWebRequest)WebRequest.Create(ftpUrl); req.Method WebRequestMethods.Ftp.GetFileSize; req.Credentials new NetworkCredential(userName, password); req.UsePassive true; using (FtpWebResponse resp (FtpWebResponse)req.GetResponse()) { return resp.ContentLength; } }第二步把本地 FileStream 的位置跳到 offset同時(shí)設(shè)置 ContentOffset數(shù)據(jù)就從指定位置繼續(xù)// 斷點(diǎn)續(xù)傳從offset位置繼續(xù)上傳 long offset GetRemoteFileSize(ftpUrl, userName, password); using (FileStream fs File.OpenRead(localPath)) { fs.Seek(offset, SeekOrigin.Begin); // 本地從對應(yīng)位置讀 FtpWebRequest request (FtpWebRequest)WebRequest.Create(ftpUrl); request.Method WebRequestMethods.Ftp.UploadFile; request.Credentials new NetworkCredential(userName, password); request.ContentOffset offset; // 服務(wù)器從對應(yīng)位置寫 request.ContentLength fileLength - offset; // 剩余長度 // ...后續(xù)循環(huán)與第3章一致 }續(xù)傳場景最容易踩三個(gè)坑。第一ContentOffset 和 ContentLength 必須一起改。只設(shè) offset 不把 ContentLength 改成剩余長度服務(wù)器會(huì)一直等數(shù)據(jù)直到超時(shí)。第二本地 FileStream 的 Seek 位置必須和 ContentOffset 嚴(yán)格一致一個(gè)傳的是 10MB 一個(gè)偏移卻是 0文件中間會(huì)有一段空洞或重復(fù)整個(gè)文件損壞。第三GetFileSize 對不存在的文件會(huì)拋 WebException很多服務(wù)端返回 550。所以首次上傳不能直接走續(xù)傳分支要捕獲異常后轉(zhuǎn)全量上傳。判斷服務(wù)器上是否存在文件除了 GetFileSize 拋異常還有更穩(wěn)妥的方式用 ListDirectory 列目錄看目標(biāo)文件名是否在返回列表里。但這種方案會(huì)增加一次網(wǎng)絡(luò)往返對于工具類程序捕獲 550 異常已經(jīng)是常見且夠用的做法。5.3 場景延伸FTP 監(jiān)控與定期同步的小工具把斷點(diǎn)續(xù)傳和進(jìn)度條組合起來能做一個(gè)實(shí)用的 FTP 監(jiān)控與定期同步工具定時(shí)掃描本地目錄把新增文件全量上傳、把中斷的任務(wù)從斷點(diǎn)續(xù)傳同時(shí)把每批次的實(shí)時(shí)進(jìn)度顯示到狀態(tài)欄。這個(gè)場景在數(shù)據(jù)采集終端、離線數(shù)據(jù)上報(bào)的運(yùn)維環(huán)境里非常常見。一個(gè)容易忽略的細(xì)節(jié)斷點(diǎn)續(xù)傳只能解決“網(wǎng)絡(luò)中斷后重連續(xù)傳”的問題如果源文件在中途被其他進(jìn)程修改了續(xù)傳會(huì)產(chǎn)生數(shù)據(jù)不一致。做定期同步之前必須確認(rèn)文件處于穩(wěn)定狀態(tài)——最簡單的方法是兩次讀取文件大小間隔 200 毫秒兩次一致才進(jìn)入上傳流程。這個(gè)“先確認(rèn)再上傳”的習(xí)慣能避免大量臟數(shù)據(jù)進(jìn)入服務(wù)器。6. 上傳后驗(yàn)證比對大小、MD5 與列目錄確認(rèn)文件真的完整進(jìn)度條到 100% 只是本地視角服務(wù)器到底收了什么還得靠驗(yàn)證。我習(xí)慣在上傳完成后強(qiáng)制走一遍三連驗(yàn)證先比對大小、再列目錄看時(shí)間戳、最后抽檢 MD5。這一步看起來多花幾十毫秒但能攔住 90% 的“假成功”。大小比對最簡單用服務(wù)器 GetFileSize 返回的值對比本地文件長度。完全一致才能進(jìn)下一步。這一步能攔住大部分字節(jié)被改寫、文件被截?cái)嗟膱鼍?。列目錄看時(shí)間戳適合確認(rèn)“服務(wù)器上的文件確實(shí)是剛才那次上傳生成的”而不是某個(gè)舊的同名文件頂替了它。MD5 校驗(yàn)最嚴(yán)謹(jǐn)?shù)鰧?。FTP 協(xié)議本身沒有標(biāo)準(zhǔn)的 MD5 校驗(yàn)命令有些服務(wù)端實(shí)現(xiàn)了 XMD5、XSHA1 這類擴(kuò)展命令但各家行為不一致。通用做法是把文件下載回來本地哈?；蛘咦尫?wù)器端腳本算好 MD5 后再寫入一個(gè)同名的 .md5 文件兩邊各算各的// 本地計(jì)算文件MD5用于上傳后與服務(wù)器端比對 public string GetFileMd5(string filePath) { using (FileStream fs File.OpenRead(filePath)) using (var md5 System.Security.Cryptography.MD5.Create()) { byte[] hash md5.ComputeHash(fs); return BitConverter.ToString(hash).Replace(-, ).ToLowerInvariant(); } }對大文件算 MD5 有 IO 開銷所以我的習(xí)慣是分級(jí)驗(yàn)證文件小于 100MB 直接算 MD5文件更大就只做大小比對加抽樣讀——取文件頭部、中部、尾部分別讀 1MB 算哈希三段一致基本能確認(rèn)傳輸無損壞。這個(gè)“三段抽樣”的辦法在帶寬有限的場景里比全量 MD5 實(shí)用得多。驗(yàn)證通過之后再更新界面狀態(tài)欄和日志文件。日志里要記錄文件路徑、服務(wù)器返回碼、傳輸耗時(shí)和驗(yàn)證結(jié)果這些數(shù)據(jù)在你排查“為什么用戶總說傳了但服務(wù)器沒有”的時(shí)候是最直接的證據(jù)。做 FTP 工具這幾年我最大的教訓(xùn)是永遠(yuǎn)不相信進(jìn)度條自己只相信校驗(yàn)結(jié)果。從那以后我每次上傳完都強(qiáng)制走一遍大小比對大文件加抽檢這個(gè)習(xí)慣幫我攔下了無數(shù)次“看似成功實(shí)則損壞”的傳輸。這份資源的完整工程代碼里已經(jīng)內(nèi)置了這三步驗(yàn)證邏輯直接跑起來就能看到效果。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 FTP上傳帶進(jìn)度條實(shí)例：C# FtpWebRequest真實(shí)進(jìn)度反饋與斷點(diǎn)續(xù)傳
簡介面向需要在桌面客戶端中實(shí)現(xiàn)FTP上傳和實(shí)時(shí)進(jìn)度反饋的.NET開發(fā)者這份C#實(shí)例完整演示了基于FTP協(xié)議分塊傳輸文件、按已上傳與總字節(jié)數(shù)比例計(jì)算進(jìn)度的實(shí)現(xiàn)方式適合C#入門學(xué)習(xí)及需要快速集成的項(xiàng)目參考。項(xiàng)目采用WinForms窗體搭建覆蓋建立連接、身份認(rèn)證、工作目錄切換、調(diào)用STOR命令上傳及回調(diào)更新進(jìn)度條等關(guān)鍵環(huán)節(jié)并在UpLoadFiles模塊中集中了上傳與進(jìn)度計(jì)算邏輯便于提取復(fù)用。資源包共35個(gè)文件壓縮后僅78KB核心為12個(gè)cs源文件輔以resources/resx界面資源、sln/csproj/config配置以及exe等編譯產(chǎn)物目錄結(jié)構(gòu)清晰可直接按窗體或工具類模塊查閱。已有868人學(xué)習(xí)下載。其中UpLoadFiles模塊里的上傳進(jìn)度計(jì)算、異常處理與重試思路以及對網(wǎng)絡(luò)延遲、文件大小限制、權(quán)限異常等常見問題的應(yīng)對策略均可遷移到實(shí)際項(xiàng)目中省去底層協(xié)議調(diào)試時(shí)間提升上傳交互體驗(yàn)。1. FTP上傳帶進(jìn)度條一份能真實(shí)反饋傳輸狀態(tài)的完整實(shí)例如果你在找 FTP 上傳帶進(jìn)度條的代碼而不是那種靠 Timer 滾動(dòng)出來的假進(jìn)度——這份實(shí)例可以直接照著做一個(gè)能用的工具。它基于 C# WinForm 實(shí)現(xiàn)用 FtpWebRequest 做協(xié)議層請求BackgroundWorker 做后臺(tái)任務(wù)進(jìn)度條顯示的是真實(shí)寫入的字節(jié)數(shù)傳多少顯示多少失敗就停在原地不會(huì)出現(xiàn)“進(jìn)度到 100% 文件卻沒到”的經(jīng)典假象。適合三類人需要給公司做文件上報(bào)、數(shù)據(jù)分發(fā)工具的開發(fā)者剛接觸 FtpWebRequest 想直接抄代碼的新手以及被假進(jìn)度條坑過、想徹底改掉這個(gè)壞習(xí)慣的運(yùn)維。下文從請求鏈路講起逐步落到可運(yùn)行的完整實(shí)現(xiàn)。提示這份資源是一套可運(yùn)行的 C# WinForm 工程源碼核心功能就一個(gè)——把本地文件通過 FTP 傳到服務(wù)器并且全程顯示真實(shí)進(jìn)度。2. FtpWebRequest 上傳鏈路先看清請求模型和進(jìn)度數(shù)據(jù)從哪來2.1 一次上傳請求的完整生命周期控制連接與數(shù)據(jù)連接的分工FTP 和 HTTP 最大的區(qū)別在于FTP 有兩條獨(dú)立的通道?？刂七B接負(fù)責(zé)傳指令USER、PASS、STOR、QUIT 這些數(shù)據(jù)連接才是真正搬運(yùn)文件字節(jié)內(nèi)容的管道。FtpWebRequest 雖然把這兩條通道封裝成了一個(gè)對象但它底層做的工作并沒有變——理解這一點(diǎn)能幫你省下大量查日志的時(shí)間。一次完整的 FtpWebRequest.UploadFile 請求內(nèi)部大致按這個(gè)順序執(zhí)行建立到服務(wù)器 21 端口的 TCP 控制連接發(fā)送 USER、PASS 完成身份認(rèn)證對應(yīng)的是你設(shè)置的 Credentials根據(jù) UsePassive 屬性決定數(shù)據(jù)通道的建立方式——被動(dòng)模式PASV是客戶端主動(dòng)連接服務(wù)器開放的數(shù)據(jù)端口主動(dòng)模式PORT是服務(wù)器回頭連你的客戶端。公網(wǎng)、內(nèi)網(wǎng)穿透、帶防火墻的環(huán)境基本都推薦被動(dòng)模式發(fā)送 STOR 命令向服務(wù)器聲明“我要上傳這個(gè)文件”文件名就是 URL 里最后一個(gè)路徑段數(shù)據(jù)通道建立后客戶端把文件字節(jié)流寫入 GetRequestStream() 拿到的 Stream寫完后關(guān)閉數(shù)據(jù)連接服務(wù)器返回 226 Transfer complete 確認(rèn)收完如果沒設(shè) KeepAlivefalse控制連接還會(huì)保持一段時(shí)間方便你繼續(xù)發(fā)下一條命令。這套流程能解釋絕大部分上傳問題。你看到請求拋異常先按返回碼定位530 是認(rèn)證失敗550 是文件操作不合法425/426 是數(shù)據(jù)通道建立失敗。我見過不少人把這幾類錯(cuò)誤混為一談?chuàng)Q了半天服務(wù)器配置最后發(fā)現(xiàn)只是賬號(hào)密碼不對。選被動(dòng)還是主動(dòng)在真實(shí)環(huán)境里經(jīng)常是個(gè)玄學(xué)問題。公司出網(wǎng)防火墻一般只放行出站連接主動(dòng)模式的 PORT 命令要求服務(wù)器回連你客戶端的隨機(jī)端口大概率被防火墻攔掉。所以現(xiàn)代 FTP 客戶端默認(rèn)都是被動(dòng)模式。但被動(dòng)模式下服務(wù)器開放的臨時(shí)數(shù)據(jù)端口范圍如果被服務(wù)端防火墻限制得很窄又會(huì)出現(xiàn)控制連接秒開、數(shù)據(jù)通道超時(shí)的怪象。這種問題排查起來最像玄學(xué)——換一個(gè)端口范圍就好了?？傊瓼tpWebRequest 里設(shè) UsePassivetrue 的同時(shí)最好讓 FTP 服務(wù)端把被動(dòng)端口范圍放寬并固定下來日志里看到 Entering Passive Mode 時(shí)能對得上端口區(qū)間就知道該去哪里查了。2.2 進(jìn)度數(shù)據(jù)從哪來Stream 層的字節(jié)計(jì)數(shù)是唯一可靠來源進(jìn)度條的本質(zhì)是“已上傳字節(jié)數(shù)”除以“總字節(jié)數(shù)”。想拿到這個(gè)可靠數(shù)據(jù)必須在文件字節(jié)流這一層數(shù)數(shù)——也就是你自己負(fù)責(zé)讀本地文件再寫入請求流每一步記錄累加值。很多圖省事的人直接調(diào) UploadFile 這類一鍵方法內(nèi)部把整個(gè)文件吞進(jìn)去你拿不到中間狀態(tài)進(jìn)度條就只能靠猜。所以我在這個(gè)工程里刻意把“讀”和“寫”拆開用循環(huán)一塊一塊地搬// 手動(dòng)讀取本地文件寫入FTP請求流每塊記錄一次進(jìn)度 using (FileStream fs File.OpenRead(localPath)) using (Stream requestStream request.GetRequestStream()) { byte[] buffer new byte[64 * 1024]; // 緩沖區(qū)大小64KB int bytesRead; long total 0; while ((bytesRead fs.Read(buffer, 0, buffer.Length)) 0) { requestStream.Write(buffer, 0, bytesRead); total bytesRead; // 這里的total就是真實(shí)進(jìn)度 progress?.Report(total); } }緩沖區(qū)大小是個(gè)折中選擇64KB 內(nèi)存占用小進(jìn)度刷新粒度又足夠平滑。要是設(shè)成 4MB大文件下進(jìn)度條是幾秒一跳的頓挫感設(shè)成 512B網(wǎng)絡(luò)小包暴增服務(wù)器 CPU 也會(huì)被無謂消耗。另一個(gè)關(guān)鍵點(diǎn)是 total 必須在 Write 之后立即累加。這樣即使某次寫失敗進(jìn)度條停留的位置也是真實(shí)已經(jīng)推到網(wǎng)絡(luò)上的位置不會(huì)出現(xiàn)“顯示到了、數(shù)據(jù)沒到”的偏差。還有一個(gè)容易被忽略的細(xì)節(jié)GetRequestStream() 返回的流綁定著 FTP 數(shù)據(jù)通道狀態(tài)不能用 Stream.CopyTo 這類快捷方式。CopyTo 內(nèi)部替你讀了寫、寫了讀但你插不上手?jǐn)?shù)數(shù)。要么拆開循環(huán)自己累加要么給流套一層帶回調(diào)的包裝流。前者代碼直觀后者侵入性好但調(diào)試麻煩。對于一個(gè)小工具來說手動(dòng)循環(huán)最劃算。另外手工循環(huán)還有一個(gè)額外好處天然支持速度統(tǒng)計(jì)。循環(huán)里記錄每次 Write 的耗時(shí)用 bytesRead 除以耗時(shí)就得到實(shí)時(shí)速率。假進(jìn)度方案根本做不了這個(gè)功能因?yàn)樗途W(wǎng)絡(luò)傳輸之間沒有對應(yīng)關(guān)系。2.3 三種進(jìn)度實(shí)現(xiàn)方案對比假進(jìn)度、流計(jì)數(shù)與輪詢?yōu)榱俗屇氵x型時(shí)不用重新踩坑我把常見的三種做法做了個(gè)對比方案原理真實(shí)度適用場景缺點(diǎn)計(jì)時(shí)器假滾動(dòng)Timer 每隔 100ms 給進(jìn)度條 Value 加 1低演示 Demo、臨時(shí)工具和實(shí)際傳輸完全脫節(jié)失敗也照常滾字節(jié)流計(jì)數(shù)循環(huán)讀寫時(shí)累計(jì)實(shí)際字節(jié)數(shù)高生產(chǎn)環(huán)境、大文件、需要精確反饋必須手動(dòng)拆讀和寫代碼稍多服務(wù)器輪詢上傳期間循環(huán)調(diào) GetFileSize 探測中拿不到中間流的封裝 SDK多一次 RTT實(shí)時(shí)性差有額外開銷我只有在兩種情況下用輪詢一是上傳流程被第三方 SDK 封裝死了拿不到中間流二是斷點(diǎn)續(xù)傳時(shí)探測服務(wù)器已有字節(jié)數(shù)。平時(shí)的上傳工具字節(jié)流計(jì)數(shù)是毫無疑問的最優(yōu)解。選型最怕的是過度設(shè)計(jì)。如果只是內(nèi)網(wǎng)傳幾十 KB 的小腳本文件假進(jìn)度其實(shí)無傷大雅用戶不會(huì)盯著進(jìn)度條。但只要文件可能超過 50MB或者要跨公網(wǎng)傳到別人的服務(wù)器就必須用流計(jì)數(shù)。這個(gè)場景下進(jìn)度條承擔(dān)的不只是“好看”它還負(fù)責(zé)讓使用者判斷當(dāng)前網(wǎng)絡(luò)狀態(tài)、決定要不要中斷重傳。一個(gè)假進(jìn)度條在這種場景里就是誤導(dǎo)。還有關(guān)于憑據(jù)的一個(gè)小坑NetworkCredential 的 domain 參數(shù)對標(biāo)準(zhǔn) FTP 沒有意義但在和 Active Directory 集成的 FTP 服務(wù)端比如 IIS FTP上用戶名要寫完整或者賬號(hào)信息字段不能為空。否則會(huì)收到 332 Need account for login 這類不常見的錯(cuò)誤碼大多數(shù)人第一反應(yīng)是查服務(wù)端權(quán)限實(shí)際上只是少填了賬號(hào)字段。3. 動(dòng)手實(shí)現(xiàn)C# WinForm 的 FTP 上傳進(jìn)度條完整代碼3.1 界面布局與后臺(tái)任務(wù)設(shè)計(jì)從觸發(fā)到收尾的完整鏈路界面只需要三個(gè)控件一個(gè) ProgressBar 顯示進(jìn)度一個(gè) Label 顯示當(dāng)前狀態(tài)一個(gè) Button 觸發(fā)上傳。要支持取消就再加一個(gè)取消按鈕?？丶g的協(xié)作方式點(diǎn)擊上傳按鈕后不能直接在主線程里執(zhí)行上傳邏輯——網(wǎng)絡(luò)讀取的阻塞調(diào)用會(huì)讓整個(gè)窗體失去響應(yīng)表現(xiàn)為白屏和拖動(dòng)卡頓。正確做法是啟動(dòng) BackgroundWorker 把上傳邏輯丟到后臺(tái)線程UI 只通過事件接收進(jìn)度并更新控件。這種做法跟前端里用 Web Worker 上傳大文件是一個(gè)思路耗時(shí) IO 全部移出主線程主線程只負(fù)責(zé)渲染。WinForm 的 BackgroundWorker 就是這個(gè)角色的封裝它內(nèi)部通過 SynchronizationContext 把進(jìn)度事件封送到 UI 線程所以你在 ProgressChanged 里更新進(jìn)度條不需要寫任何 Invoke 代碼。界面設(shè)計(jì)上要留意一個(gè)原則進(jìn)度條控件本身只管顯示不要在里面塞業(yè)務(wù)邏輯。很多新手把文件大小計(jì)算、網(wǎng)速估算全塞進(jìn) ProgressChanged 回調(diào)結(jié)果 UI 線程被這些雜事拖住進(jìn)度條反而卡頓。把上傳前就確定的值文件總長度提前存字段進(jìn)度回調(diào)里只做兩件事——更新 Value、更新文案。3.2 核心上傳方法帶真實(shí)進(jìn)度計(jì)的 FtpWebRequest 封裝下面的方法建議直接復(fù)制到公共類留出進(jìn)度回調(diào)和取消檢查的接口WinForm、控制臺(tái)、Windows 服務(wù)都能復(fù)用// 帶真實(shí)進(jìn)度回傳的FTP上傳方法 // onProgress: 已上傳字節(jié)數(shù)回調(diào) // checkCancel: 返回true時(shí)終止上傳 public void UploadWithProgress( string localFilePath, string ftpUrl, string userName, string password, Actionlong onProgress, Funcbool checkCancel) { using (FileStream fs File.OpenRead(localFilePath)) { long fileLength fs.Length; FtpWebRequest request (FtpWebRequest)WebRequest.Create(ftpUrl); request.Method WebRequestMethods.Ftp.UploadFile; request.Credentials new NetworkCredential(userName, password); request.UseBinary true; // 二進(jìn)制傳輸防止字節(jié)被改寫 request.UsePassive true; // 被動(dòng)模式繞開防火墻限制 request.KeepAlive false; // 單一文件傳完即關(guān)閉連接 // 關(guān)鍵告訴服務(wù)器文件總長度否則無法判斷傳輸終態(tài) request.ContentLength fileLength; using (Stream requestStream request.GetRequestStream()) { byte[] buffer new byte[64 * 1024]; // 64KB緩沖區(qū) int bytesRead; long totalBytesWritten 0; while ((bytesRead fs.Read(buffer, 0, buffer.Length)) 0) { // 每次寫前檢查取消標(biāo)記協(xié)作式取消 if (checkCancel ! null checkCancel()) { throw new OperationCanceledException(用戶取消上傳); } requestStream.Write(buffer, 0, bytesRead); totalBytesWritten bytesRead; // 上報(bào)真實(shí)字節(jié)數(shù)給UI層 onProgress?.Invoke(totalBytesWritten); } // 沖刷緩沖避免最后一小塊數(shù)據(jù)滯留本地 requestStream.Flush(); } // 必須拿到服務(wù)器確認(rèn)響應(yīng)才算真正完成 using (FtpWebResponse response (FtpWebResponse)request.GetResponse()) { if (response.StatusCode ! FtpStatusCode.ClosingData) { throw new Exception($服務(wù)器返回異常: {response.StatusCode}); } } } }四個(gè)容易忽略的配置這里一并說清。ContentLength 不設(shè)置或設(shè)錯(cuò)服務(wù)器在數(shù)據(jù)通道關(guān)閉時(shí)可能用 451 之類的錯(cuò)誤碼拒絕文件或者一直等數(shù)據(jù)直到超時(shí)。FtpWebRequest 依賴它判斷數(shù)據(jù)流的邊界所以務(wù)必從 FileStream.Length 取真實(shí)字節(jié)數(shù)。UseBinary 決定傳輸模式。對壓縮包、圖片、PDF 這類二進(jìn)制文件如果誤用 ASCII 模式0x0A 單字節(jié)換行符會(huì)被改寫成 0x0D 0x0A 雙字節(jié)文件當(dāng)場損壞。文本文件也建議直接用二進(jìn)制模式服務(wù)器不做任何轉(zhuǎn)換兩邊字節(jié)完全一致。KeepAlivefalse 的意義在于單個(gè)文件傳完就斷開控制連接服務(wù)器端不會(huì)因?yàn)檫B接緩存讓文件句柄遲遲不釋放。循環(huán)傳多個(gè)文件時(shí)反過來KeepAlivetrue 能復(fù)用連接節(jié)省握手開銷。最后是 Flush。requestStream 內(nèi)部有緩沖不 Flush 直接 Close某些實(shí)現(xiàn)會(huì)先關(guān)閉連接再倒緩存導(dǎo)致最后一批數(shù)據(jù)還沒到服務(wù)器就斷了。寫完循環(huán)后、關(guān)閉請求流前主動(dòng) Flush是避免“進(jìn)度條 99% 卡住”的關(guān)鍵動(dòng)作。3.3 跨線程更新進(jìn)度條與狀態(tài)欄BackgroundWorker 的標(biāo)準(zhǔn)連接方式核心方法寫完接下來掛到 UI 上。這里用 BackgroundWorker 而不是 async/await是為了讓沒升級(jí)到 .NET 4.5 的舊工程也能直接抄// 點(diǎn)擊上傳按鈕后啟動(dòng)后臺(tái)任務(wù) private void btnUpload_Click(object sender, EventArgs e) { OpenFileDialog dlg new OpenFileDialog(); if (dlg.ShowDialog() ! DialogResult.OK) return; string localPath dlg.FileName; string uploadUrl ftp://192.168.1.100/share/ Path.GetFileName(localPath); long totalLength new FileInfo(localPath).Length; // 提前緩存避免回調(diào)里反復(fù)IO BackgroundWorker worker new BackgroundWorker(); worker.WorkerReportsProgress true; worker.WorkerSupportsCancellation true; // 后臺(tái)執(zhí)行上傳邏輯 worker.DoWork (s, e2) { try { UploadWithProgress( localPath, uploadUrl, ftpuser, ftppass, // 每次回調(diào)都報(bào)告百分比UserState傳出字節(jié)數(shù) (bytes) { int percent (int)(bytes * 100 / totalLength); worker.ReportProgress(percent, bytes); }, // 取消檢查直接讀標(biāo)志位 () worker.CancellationPending ); } catch (OperationCanceledException) { e2.Cancel true; // 用戶取消不按失敗處理 } catch (Exception ex) { e2.Result ex; // 異常帶回UI線程 } }; // 更新進(jìn)度條與狀態(tài)欄 worker.ProgressChanged (s, e2) { progressBar.Value e2.ProgressPercentage; long bytes (long)e2.UserState; lblStatus.Text $已上傳 {FormatFileSize(bytes)} / {FormatFileSize(totalLength)}; }; // 上傳完成后的收尾 worker.RunWorkerCompleted (s, e2) { if (e2.Cancelled) { lblStatus.Text 已取消上傳; } else if (e2.Result is Exception ex) { lblStatus.Text 上傳失敗 ex.Message; } else { lblStatus.Text 上傳完成; } progressBar.Value 0; }; worker.RunWorkerAsync(); }進(jìn)度更新這個(gè)環(huán)節(jié)最常報(bào)的錯(cuò)是“跨線程操作無效”。DoWork 跑在后臺(tái)線程直接操作 progressBar 必然拋 InvalidOperationException。BackgroundWorker 的 ReportProgress 機(jī)制會(huì)自動(dòng)封送到 UI 線程所以 ProgressChanged 里不需要任何 Invoke 代碼。這條規(guī)則不僅適用進(jìn)度條狀態(tài)欄、列表控件都是同樣的處理方式。取消按鈕的配合也很簡單取消按鈕里調(diào) worker.CancelAsync()然后立刻把取消按鈕禁用、上傳按鈕恢復(fù)防止重復(fù)點(diǎn)擊。CancelAsync 不會(huì)中斷正在執(zhí)行的代碼它只是把 CancellationPending 置為 true循環(huán)必須主動(dòng)檢查這個(gè)標(biāo)志才能退出。這就是協(xié)作式取消在 BackgroundWorker 里體現(xiàn)得最典型。3.4 關(guān)鍵參數(shù)清單按生產(chǎn)標(biāo)準(zhǔn)一次設(shè)對參數(shù)推薦值說明UseBinarytrue二進(jìn)制傳輸防止換行符被改寫UsePassivetrue被動(dòng)模式減少防火墻影響KeepAlivefalse單文件上傳后斷開控制連接ContentLength本地文件長度必須設(shè)置否則服務(wù)器無法確認(rèn)文件邊界Timeout30000ms建立連接和發(fā)送命令的超時(shí)ReadWriteTimeout60000ms單個(gè)讀寫操作的最大耗時(shí)緩沖區(qū)64KB內(nèi)存與網(wǎng)絡(luò)包數(shù)量的折中Timeout 和 ReadWriteTimeout 是兩回事這點(diǎn)很多人栽過。Timeout 管連接建立和命令收發(fā)ReadWriteTimeout 管數(shù)據(jù)流的單次讀寫。弱網(wǎng)下傳大文件默認(rèn) 30 秒的 ReadWriteTimeout 可能不夠網(wǎng)絡(luò)抖動(dòng)一下讀寫就中斷了。按文件大小和帶寬估算留出余量再設(shè)。另外把 FTP 當(dāng)內(nèi)部文件共享用跨網(wǎng)段比 SMB 省心是常見做法但一定要給共享目錄配專用賬號(hào)別用匿名登錄。匿名賬號(hào)在不少服務(wù)端被設(shè)置為只讀上傳時(shí)總是神秘失敗日志看不出來最后發(fā)現(xiàn)是權(quán)限位不對。4. 避坑與常見問題進(jìn)度條翻車的五個(gè)真實(shí)場景4.1 現(xiàn)象進(jìn)度卡在 99% 不動(dòng)最后拋超時(shí)異常原因請求流內(nèi)部的緩沖區(qū)沒有沖刷干凈數(shù)據(jù)還滯留在本地就關(guān)閉了連接服務(wù)器等不到最后一個(gè)數(shù)據(jù)塊超時(shí)斷開。解決關(guān)流之前顯式調(diào)用 requestStream.Flush()。同時(shí)檢查循環(huán)里是否把 Close 寫在了所有 Write 完成之前。我最初寫的版本就是 Write 完直接 Close導(dǎo)致最后一塊數(shù)據(jù)總是丟。從那以后我關(guān)閉任何網(wǎng)絡(luò)流的順序都固定為寫完 → Flush → Close一步不亂。4.2 現(xiàn)象進(jìn)度條到 100%服務(wù)器上卻找不到文件原因最常見的有兩個(gè)。一是 UseBinary 沒設(shè) true二進(jìn)制文件被傳輸模式改寫字節(jié)服務(wù)端校驗(yàn)失敗后丟棄二是請求流寫完就關(guān)沒等 GetResponse() 拿到 226 確認(rèn)。解決使用二進(jìn)制模式并保留到 GetResponse() 返回 226 才算真正結(jié)束。進(jìn)度到 100% 只代表本地流寫完不等于服務(wù)器確認(rèn)收完。如果你用第 3 章的封裝這段邏輯已經(jīng)包含在內(nèi)不要手動(dòng)提前釋放 request。4.3 現(xiàn)象大文件一上傳界面就假死拖動(dòng)窗口都費(fèi)勁原因上傳邏輯跑在 UI 線程FtpWebRequest 同步方法讀取網(wǎng)絡(luò)流時(shí)阻塞線程窗口消息全部排隊(duì)界面自然無響應(yīng)。解決把上傳丟到 BackgroundWorker 或 Task.Run 里。如果已經(jīng)用了后臺(tái)線程但還是卡檢查 ProgressChanged 回調(diào)里有沒有耗時(shí)操作——有人習(xí)慣在回調(diào)里 new FileInfo(localPath).Length 重新取文件大小文件一大這步磁盤 IO 就能拖慢 UI。文件總長度應(yīng)在點(diǎn)擊上傳時(shí)就緩存好回調(diào)里只做控件賦值。4.4 現(xiàn)象上傳中斷后服務(wù)器殘留半截文件下次繼續(xù)傳也不完整原因取消或斷網(wǎng)時(shí)服務(wù)端已經(jīng)創(chuàng)建了目標(biāo)文件并寫入了部分字節(jié)但因?yàn)闆]收到結(jié)束標(biāo)志文件被留在異常狀態(tài)。解決在取消和異常處理中主動(dòng)發(fā) DELE 命令刪除殘留文件或者實(shí)現(xiàn)斷點(diǎn)續(xù)傳。第 5 章會(huì)給出 DELE 清理的完整代碼。這里先記住一個(gè)原則取消上傳不只是中斷本地循環(huán)還要向服務(wù)器聲明“我剛才那個(gè)文件不算數(shù)”否則你會(huì)在服務(wù)器上留一堆垃圾文件。4.5 現(xiàn)象返回 530 Authentication failed賬號(hào)密碼看著沒錯(cuò)原因很多 FTP 服務(wù)器開了賬號(hào)鎖定策略密碼連續(xù)錯(cuò)幾次會(huì)鎖一段時(shí)間或者服務(wù)端要求顯式 TLS。還有一種情況賬號(hào)是弱口令被安全掃描器探測并鎖定了你在客戶端這邊看賬號(hào)密碼完全沒問題。解決先登錄 FTP 服務(wù)端管理界面看賬號(hào)狀態(tài)再確認(rèn)是否強(qiáng)制 FTPS。FtpWebRequest 里設(shè)置 EnableSsl true 即可走加密通道。生產(chǎn)環(huán)境一定單獨(dú)建低權(quán)限專用賬號(hào)別用 root 或管理員級(jí)別的賬號(hào)連應(yīng)用順手把 FTP 弱口令這個(gè)隱患也堵上。5. 進(jìn)階取消與斷點(diǎn)續(xù)傳——把進(jìn)度條升級(jí)成可中斷任務(wù)5.1 協(xié)作式取消的完整閉環(huán)中斷循環(huán)、清理殘留、通知上層第 3 章用的 BackgroundWorker.CancellationPending 是標(biāo)準(zhǔn)的協(xié)作式取消。如果你的代碼要復(fù)用進(jìn) Windows Service 或命令行工具更通用的做法是注入 CancellationToken。無論哪種方式核心都在于“循環(huán)內(nèi)部自己檢查標(biāo)記、自己退出”。退出之后的清理動(dòng)作往往被忽略。中斷上傳時(shí)服務(wù)器上已經(jīng)生成了一個(gè)不完整的文件正確順序是先拋出 OperationCanceledException 退出循環(huán)然后在 catch 塊里發(fā)一條 DELE 命令刪除目標(biāo)文件最后再重新拋出讓上層感知// 取消上傳時(shí)清理服務(wù)器殘留的半截文件 catch (OperationCanceledException) { try { FtpWebRequest delRequest (FtpWebRequest)WebRequest.Create(ftpUrl); delRequest.Method WebRequestMethods.Ftp.DeleteFile; delRequest.Credentials new NetworkCredential(userName, password); using (FtpWebResponse delResponse (FtpWebResponse)delRequest.GetResponse()) { // 刪除成功或返回550文件不存在都視為清理完成 } } catch { // 清理失敗不阻斷主流程 } throw; }DELE 命令走的是控制連接不涉及數(shù)據(jù)通道所以即使數(shù)據(jù)流已經(jīng)中斷這條命令大概率還能成功。如果服務(wù)端本身有殘留文件自動(dòng)清理策略這一步可以省略但作為應(yīng)用層兜底做了永遠(yuǎn)比不做好。這里的核心思想是取消操作要保證“不留臟數(shù)據(jù)”這比“快速退出”更重要。5.2 斷點(diǎn)續(xù)傳ContentOffset 與服務(wù)器已有文件大小的配合斷點(diǎn)續(xù)傳的底層是 FTP 的 REST 命令客戶端先發(fā)REST 1024再發(fā) STOR服務(wù)端就從第 1024 個(gè)字節(jié)開始繼續(xù)寫入。FtpWebRequest 里對應(yīng)的是 ContentOffset 屬性設(shè)置后框架會(huì)自動(dòng)在 STOR 前發(fā)送 REST 命令。實(shí)現(xiàn)分兩步。第一步探測服務(wù)器上已有的文件大小// 探測服務(wù)器已存在文件的大小用于斷點(diǎn)續(xù)傳 private long GetRemoteFileSize(string ftpUrl, string userName, string password) { FtpWebRequest req (FtpWebRequest)WebRequest.Create(ftpUrl); req.Method WebRequestMethods.Ftp.GetFileSize; req.Credentials new NetworkCredential(userName, password); req.UsePassive true; using (FtpWebResponse resp (FtpWebResponse)req.GetResponse()) { return resp.ContentLength; } }第二步把本地 FileStream 的位置跳到 offset同時(shí)設(shè)置 ContentOffset數(shù)據(jù)就從指定位置繼續(xù)// 斷點(diǎn)續(xù)傳從offset位置繼續(xù)上傳 long offset GetRemoteFileSize(ftpUrl, userName, password); using (FileStream fs File.OpenRead(localPath)) { fs.Seek(offset, SeekOrigin.Begin); // 本地從對應(yīng)位置讀 FtpWebRequest request (FtpWebRequest)WebRequest.Create(ftpUrl); request.Method WebRequestMethods.Ftp.UploadFile; request.Credentials new NetworkCredential(userName, password); request.ContentOffset offset; // 服務(wù)器從對應(yīng)位置寫 request.ContentLength fileLength - offset; // 剩余長度 // ...后續(xù)循環(huán)與第3章一致 }續(xù)傳場景最容易踩三個(gè)坑。第一ContentOffset 和 ContentLength 必須一起改。只設(shè) offset 不把 ContentLength 改成剩余長度服務(wù)器會(huì)一直等數(shù)據(jù)直到超時(shí)。第二本地 FileStream 的 Seek 位置必須和 ContentOffset 嚴(yán)格一致一個(gè)傳的是 10MB 一個(gè)偏移卻是 0文件中間會(huì)有一段空洞或重復(fù)整個(gè)文件損壞。第三GetFileSize 對不存在的文件會(huì)拋 WebException很多服務(wù)端返回 550。所以首次上傳不能直接走續(xù)傳分支要捕獲異常后轉(zhuǎn)全量上傳。判斷服務(wù)器上是否存在文件除了 GetFileSize 拋異常還有更穩(wěn)妥的方式用 ListDirectory 列目錄看目標(biāo)文件名是否在返回列表里。但這種方案會(huì)增加一次網(wǎng)絡(luò)往返對于工具類程序捕獲 550 異常已經(jīng)是常見且夠用的做法。5.3 場景延伸FTP 監(jiān)控與定期同步的小工具把斷點(diǎn)續(xù)傳和進(jìn)度條組合起來能做一個(gè)實(shí)用的 FTP 監(jiān)控與定期同步工具定時(shí)掃描本地目錄把新增文件全量上傳、把中斷的任務(wù)從斷點(diǎn)續(xù)傳同時(shí)把每批次的實(shí)時(shí)進(jìn)度顯示到狀態(tài)欄。這個(gè)場景在數(shù)據(jù)采集終端、離線數(shù)據(jù)上報(bào)的運(yùn)維環(huán)境里非常常見。一個(gè)容易忽略的細(xì)節(jié)斷點(diǎn)續(xù)傳只能解決“網(wǎng)絡(luò)中斷后重連續(xù)傳”的問題如果源文件在中途被其他進(jìn)程修改了續(xù)傳會(huì)產(chǎn)生數(shù)據(jù)不一致。做定期同步之前必須確認(rèn)文件處于穩(wěn)定狀態(tài)——最簡單的方法是兩次讀取文件大小間隔 200 毫秒兩次一致才進(jìn)入上傳流程。這個(gè)“先確認(rèn)再上傳”的習(xí)慣能避免大量臟數(shù)據(jù)進(jìn)入服務(wù)器。6. 上傳后驗(yàn)證比對大小、MD5 與列目錄確認(rèn)文件真的完整進(jìn)度條到 100% 只是本地視角服務(wù)器到底收了什么還得靠驗(yàn)證。我習(xí)慣在上傳完成后強(qiáng)制走一遍三連驗(yàn)證先比對大小、再列目錄看時(shí)間戳、最后抽檢 MD5。這一步看起來多花幾十毫秒但能攔住 90% 的“假成功”。大小比對最簡單用服務(wù)器 GetFileSize 返回的值對比本地文件長度。完全一致才能進(jìn)下一步。這一步能攔住大部分字節(jié)被改寫、文件被截?cái)嗟膱鼍?。列目錄看時(shí)間戳適合確認(rèn)“服務(wù)器上的文件確實(shí)是剛才那次上傳生成的”而不是某個(gè)舊的同名文件頂替了它。MD5 校驗(yàn)最嚴(yán)謹(jǐn)?shù)鰧?。FTP 協(xié)議本身沒有標(biāo)準(zhǔn)的 MD5 校驗(yàn)命令有些服務(wù)端實(shí)現(xiàn)了 XMD5、XSHA1 這類擴(kuò)展命令但各家行為不一致。通用做法是把文件下載回來本地哈?；蛘咦尫?wù)器端腳本算好 MD5 后再寫入一個(gè)同名的 .md5 文件兩邊各算各的// 本地計(jì)算文件MD5用于上傳后與服務(wù)器端比對 public string GetFileMd5(string filePath) { using (FileStream fs File.OpenRead(filePath)) using (var md5 System.Security.Cryptography.MD5.Create()) { byte[] hash md5.ComputeHash(fs); return BitConverter.ToString(hash).Replace(-, ).ToLowerInvariant(); } }對大文件算 MD5 有 IO 開銷所以我的習(xí)慣是分級(jí)驗(yàn)證文件小于 100MB 直接算 MD5文件更大就只做大小比對加抽樣讀——取文件頭部、中部、尾部分別讀 1MB 算哈希三段一致基本能確認(rèn)傳輸無損壞。這個(gè)“三段抽樣”的辦法在帶寬有限的場景里比全量 MD5 實(shí)用得多。驗(yàn)證通過之后再更新界面狀態(tài)欄和日志文件。日志里要記錄文件路徑、服務(wù)器返回碼、傳輸耗時(shí)和驗(yàn)證結(jié)果這些數(shù)據(jù)在你排查“為什么用戶總說傳了但服務(wù)器沒有”的時(shí)候是最直接的證據(jù)。做 FTP 工具這幾年我最大的教訓(xùn)是永遠(yuǎn)不相信進(jìn)度條自己只相信校驗(yàn)結(jié)果。從那以后我每次上傳完都強(qiáng)制走一遍大小比對大文件加抽檢這個(gè)習(xí)慣幫我攔下了無數(shù)次“看似成功實(shí)則損壞”的傳輸。這份資源的完整工程代碼里已經(jīng)內(nèi)置了這三步驗(yàn)證邏輯直接跑起來就能看到效果。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取