簡介面向需要在Windows桌面端實現(xiàn)藍牙低功耗BLE通信的C#開發(fā)人員資源提供了一套基于WinForm的完整示例工程。工程調(diào)用Windows.Devices.Bluetooth API實現(xiàn)了Windows下BLE設(shè)備的自動連接與收發(fā)數(shù)據(jù)繞開UWP開發(fā)限制可直接在VS2022中打開并編譯運行。壓縮包共32個文件包含F(xiàn)orm1.cs、BleCore.cs等8個C#源碼文件以及工程配置、界面資源、庫引用winmd、可執(zhí)行exe和調(diào)試pdb等整體約2.39MB。核心邏輯集中在BleCore.cs中便于學(xué)習設(shè)備發(fā)現(xiàn)、配對連接及GATT數(shù)據(jù)交互流程同時附帶App.config與Settings配置幫助理解參數(shù)管理與多分辨率下的界面布局。目前已有3710人學(xué)習下載適合希望快速落地Windows BLE桌面應(yīng)用的中級C#開發(fā)者參考。1. 為什么 WinForms 里搞 BLE 這么別扭API 選型的現(xiàn)實問題先說個我自己的經(jīng)歷。去年接手一個產(chǎn)線測試工具需求很簡單在 Windows 上位機上用 C# WinForms 掃到周邊的藍牙低功耗BLE傳感器連上去讀一組特征值再把數(shù)據(jù)懟進數(shù)據(jù)庫。聽起來是個常規(guī)活結(jié)果真做起來發(fā)現(xiàn)Windows 上的 BLE 開發(fā)資料少得可憐官方 Demo 十個里有八個是 UWP 的剩下兩個還是 C/WinRT 的想在自己熟悉的老 WinForms 項目里用起來得先繞好幾個彎。1.1 不是所有藍牙 API 都能用Windows 上操作藍牙低功耗其實有幾條路UWP 的 Windows.Devices.Bluetooth 命名空間這是微軟主推的 BLE API功能最全支持廣播掃描、GATT 服務(wù)、特征讀寫、通知訂閱長期維護。經(jīng)典藍牙的 System.IO.Ports 串口方式SPP/RFCOMM只適合傳統(tǒng)藍牙BLE 根本走不了這條路。第三方庫如 32feet.NET對 BLE 的支持一直不完整很多年沒大更新做做經(jīng)典藍牙還行搞 BLE 容易卡在服務(wù)發(fā)現(xiàn)和通知上。直接用底層 Win32 API 調(diào)用 BluetoothGATT系列函數(shù)*理論上可行但代碼量極大處理回調(diào)、緩存、異步模型足夠你寫掉兩周時間。所以只要你做的是 BLE 設(shè)備通信基本就鎖定了第一條路把 Windows.Devices.Bluetooth 這套 WinRT API 拉到 .NET 桌面應(yīng)用里來用。好消息是微軟提供了Microsoft.Windows.SDK.Contracts這個 NuGet 包讓 WinForms 和 WPF 都能直接調(diào)用 WinRT API不需要額外打包成 UWP 應(yīng)用。我實測 .NET Framework 4.7.2 和 .NET 6/8 下都能跑通建議新項目直接用 .NET 6 以上異步體驗和內(nèi)存管理都好不少。1.2 項目配置與權(quán)限聲明第一步很容易踩坑很多人在這一步就卡住。直接在 WinForms 項目里寫了BluetoothLEDevice.FromIdAsync一運行就拋異常System.Runtime.InteropServices.COMException提示類未注冊或者拒絕訪問。原因通常是兩個第一項目沒有正確引用 WinRT API。如果你用 .NET Framework需要在 NuGet 里安裝Microsoft.Windows.SDK.Contracts如果你用 .NET 6/7/8直接啟用TargetFramework 的net8.0-windows10.0.19041.0這種形式系統(tǒng)會自動帶上所需引用。我比較推薦后者寫net8.0-windows10.0.19041.0就不用再單獨裝包了而且 API 版本也新。第二你沒有聲明藍牙權(quán)限。沒錯WinForms 雖是桌面應(yīng)用但調(diào)用藍牙 API 時系統(tǒng)會檢查 appxmanifest 里的 capability。如果你的項目是從 UWP 遷過來的那還好說如果是純 WinForms 項目你需要手動加或改app.manifest/Package.appxmanifest文件在里面加上Capabilities DeviceCapability Namebluetooth / /Capabilities如果你沒有打包成 MSIX只是以普通 exe 運行很多情況下不聲明也能跑但一旦你觸發(fā)了系統(tǒng)級藍牙權(quán)限彈窗或 UWP 兼容層就會出現(xiàn)詭異的“間歇性可用”問題。我的建議是既然要長期維護干脆加上省得用戶換臺機器就崩。還有一個 Silent 坑Windows 的藍牙權(quán)限分“首次提示”和“始終允許”。如果你在虛擬機或遠程桌面環(huán)境下調(diào)試藍牙適配器根本不可見API 返回空集合這時候別懷疑代碼先確認宿主機藍牙是開啟狀態(tài)并且賬號有硬件訪問權(quán)限。我在一臺 Windows Server 2019 上調(diào)試時折騰了兩小時最后發(fā)現(xiàn)是遠程會話把藍牙設(shè)備全部屏蔽了。2. 設(shè)備掃描廣播、RSSI 與地址陷阱掃描 BLE 外設(shè)用的是BluetoothLEAdvertisementWatcher它本質(zhì)上是一個被動監(jiān)聽廣播包的組件。你可以把它理解為電臺收音機外設(shè)不停地在 2.4GHz 頻段上發(fā)廣播Advertisements你的 watcher 負責“收臺”收到后給你回調(diào)。2.1 掃不掃得到和廣播類型有關(guān)系先看最基礎(chǔ)的掃描寫法var watcher new BluetoothLEAdvertisementWatcher(); watcher.ScanningMode BluetoothLEScanningMode.Active; watcher.SignalStrengthFilter.InRangeThresholdInDBm -80; watcher.SignalStrengthFilter.OutOfRangeThresholdInDBm -100; watcher.Received OnAdvertisementReceived; watcher.Start();回調(diào)里能拿到的信息包括BluetoothAddress設(shè)備的 MAC實際是 48 位地址RawSignalStrengthInDBm信號強度 RSSIAdvertisementType廣播類型連接廣播、可掃描廣播等Advertisement.LocalName設(shè)備名Advertisement.ServiceUuids廣播里攜帶的服務(wù) UUID需要說明的是廣播類型的影響非常大。BLE 外設(shè)至少有兩種典型廣播方式一種是每 100ms 發(fā)一個可連接廣播ADV_IND這種你掃到的概率很大另一種是省電模式幾秒鐘才廣播一次甚至只有在被主動掃描時才回應(yīng)掃描請求ADV_SCAN_IND。如果設(shè)備設(shè)置的廣播間隔是 2 秒你的窗口剛好錯過那可能這回合并掃不到。實測下來把手環(huán)、傳感器類設(shè)備的廣播間隔調(diào)到 200ms 以下掃描成功率才比較理想。另外Windows 的BluetoothLEAdvertisementWatcher對掃描功耗沒有 Android 那么敏感你大可以直接用Active模式它允許設(shè)備在收到掃描請求后返回額外的數(shù)據(jù)比如某些設(shè)備會把完整的服務(wù)列表和設(shè)備名放在掃描響應(yīng)里。用Passive模式雖然省資源但能拿到的信息少很多容易誤判設(shè)備。2.2 掃描回調(diào)里的地址陷阱這是我踩過最深的一個坑必須單獨拿出來說。在OnAdvertisementReceived回調(diào)里你會拿到BluetoothAddress這個地址看起來像個 MAC但你不能直接拿它去拼字符串然后傳給BluetoothLEDevice.FromBluetoothAddressAsync。為什么因為 Windows 對 BLE 設(shè)備的標識推薦使用deviceId設(shè)備實例 ID而不是地址。原因有兩點部分外設(shè)開啟了地址隨機化Privacy 功能每次廣播 MAC 都會變你拿地址根本連不上同一個設(shè)備可能通過多種協(xié)議暴露BLE Classic設(shè)備實例 ID 才是系統(tǒng)內(nèi)部統(tǒng)一的標識。正確的做法是在回調(diào)里通過e.BluetoothAddress拼出設(shè)備 ID或者直接獲取系統(tǒng)分配的DeviceInformation.Id。下面這個代碼我一直在用比較穩(wěn)定private async void OnAdvertisementReceived(BluetoothLEAdvertisementReceivedEventArgs args) { // 先過濾掉空設(shè)備名或者按信號強度過濾 if (string.IsNullOrEmpty(args.Advertisement.LocalName)) return; if (args.RawSignalStrengthInDBm -75) return; // 推薦用 FromBluetoothAddressAsync廣播里的地址仍然有效 // 但需要設(shè)置 AddressType避免隨機地址被當成公共地址處理 var device await BluetoothLEDevice.FromBluetoothAddressAsync(args.BluetoothAddress, args.BluetoothAddressType); if (device null) return; // 也可以從這里拿 device.DeviceId 存下來后續(xù)連接用它 string deviceId device.DeviceId; }注意AddressType一定別漏。如果設(shè)備是隨機地址Random你卻按 Public 處理后續(xù) GATT 連接會一直超時。我見過不少人在網(wǎng)上提問為什么連得上、發(fā)不了數(shù)據(jù)最后發(fā)現(xiàn)就是地址類型沒傳對。掃描啟停也要記得做防抖。watcher.Stop()之后最好加個await Task.Delay(500)再重啟掃描否則在某些驅(qū)動版本上會出現(xiàn)掃描假死即回調(diào)不再觸發(fā)但 watcher 狀態(tài)顯示已在運行。這種問題重啟電腦能解決但你不能讓操作工老重啟機器。3. 建立連接與 GATT 服務(wù)發(fā)現(xiàn)從“掃到”到“連上”之間的事掃描到設(shè)備只是第一步。BLE 的連接過程其實是這樣的客戶端先跟設(shè)備建立鏈路層連接然后做 GATT 層的服務(wù)發(fā)現(xiàn)拿到這個設(shè)備公開了哪些 Service、每個 Service 下有哪些 Characteristic特征值。服務(wù)發(fā)現(xiàn)完成后你才能知道往哪個句柄讀數(shù)據(jù)、寫數(shù)據(jù)。3.1 連接之前先想清楚拿什么當 Key實戰(zhàn)里最常見的場景是界面上一個 ListView 列出掃描結(jié)果設(shè)備名 地址用戶選一個點“連接”程序去連。這時候你用什么標識去調(diào)FromBluetoothAddressAsync還是FromIdAsync我的建議是掃描階段就保存兩份數(shù)據(jù)BluetoothAddress和DeviceId。通常優(yōu)先用FromIdAsync因為設(shè)備 ID 是系統(tǒng)分配的穩(wěn)定句柄連接成功率高但如果你需要跨會話恢復(fù)連接比如讓程序記住上次連的好幾個設(shè)備存 DeviceId 更可靠。// 用 DeviceId 連接 BluetoothLEDevice device await BluetoothLEDevice.FromIdAsync(deviceId); // 用地址連接備用方案注意地址類型 BluetoothLEDevice device2 await BluetoothLEDevice.FromBluetoothAddressAsync(address, BluetoothAddressType.Public);連接過程中務(wù)必訂閱ConnectionStatusChanged事件這樣能第一時間知道設(shè)備掉了還是重新連上了。否則你可能會在寫入時才發(fā)現(xiàn)連接早就斷了然后被一堆Exception搞得一臉懵。device.ConnectionStatusChanged Device_ConnectionStatusChanged;補充一個實用技巧如果你要做自動重連建議在事件里判斷device.ConnectionStatus BluetoothConnectionStatus.Disconnected后等待 12 秒再嘗試重新連接而不是立刻重連。原因有二一是設(shè)備可能還沒恢復(fù)到可連接廣播狀態(tài)二是 Windows 對快速反復(fù)連接同一設(shè)備有時會返回BluetoothError.DeviceNotAvailable需要冷卻一下。3.2 服務(wù)與特征的查找方式連接成功后就要去拿 GATT 服務(wù)了。這一步有坑GetGattServicesAsync默認會使用緩存數(shù)據(jù)。如果設(shè)備端升級固件或者在連接期間改變了服務(wù)結(jié)構(gòu)你拿到的是舊的緩存導(dǎo)致某個特征找不到。解決方法是使用帶BluetoothCacheMode.Uncached參數(shù)的重載GattDeviceServicesResult result await device.GetGattServicesAsync(BluetoothCacheMode.Uncached); if (result.Status ! GattCommunicationStatus.Success) { // 處理失敗 return; } foreach (var service in result.Services) { // 按 UUID 篩選比如 電池服務(wù) 0x180F if (service.Uuid GattServiceUuids.Battery) { var characteristicResult await service.GetCharacteristicsAsync(BluetoothCacheMode.Uncached); foreach (var characteristic in characteristicResult.Characteristics) { // 找到你要的特征 } } }注意GetGattServicesAsync返回后service對象不能一直拿著不放。如果你的程序里有很多邏輯到處引用同一個 service 實例設(shè)備斷開重連后這個實例就無效了必須重新FromIdAsync再拿一次。我習慣的做法是寫一個BleDeviceManager類把設(shè)備、連接狀態(tài)、GATT 特性全部封裝好斷開時統(tǒng)一清理引用。特征值的屬性也要提前搞清楚。你拿到一個GattCharacteristic要讀它的CharacteristicProperties判斷是Read、WriteWithoutResponse還是Notify。如果你對一個只支持 Notify 的特征調(diào)用ReadValueAsync會直接返回Unreachable或者拋異常。先判斷再操作是避免低級 Bug 的好習慣。4. 讀寫特征與通知訂閱BLE 交互的核心戰(zhàn)場整個 BLE 開發(fā)里最核心的就是對特征值進行讀、寫、訂閱通知這三類操作。數(shù)據(jù)收發(fā)、協(xié)議解析全在這里。4.1 特征值讀寫讀操作很簡單GattReadResult readResult await characteristic.ReadValueAsync(BluetoothCacheMode.Uncached); if (readResult.Status GattCommunicationStatus.Success) { var reader DataReader.FromBuffer(readResult.Value); byte[] data new byte[reader.UnconsumedBufferLength]; reader.ReadBytes(data); // 繼續(xù)解析 }寫操作稍微講究一點。BLE 有兩種寫模式Write With Response設(shè)備收到數(shù)據(jù)后會回一個確認包可靠性高但速度慢Write Without Response發(fā)出去不管速度快但可能丟包對應(yīng)到 API 就是WriteValueAsync(byte[])默認走前者WriteValueWithResultAsync可以看到結(jié)果。如果設(shè)備協(xié)議要求快速寫入比如按鍵遙控器、連續(xù)調(diào)速指令建議用GattWriteOption.WriteWithoutResponseawait characteristic.WriteValueAsync(buffer, GattWriteOption.WriteWithoutResponse);這個選項要謹慎使用。盲寫模式下如果設(shè)備端正處于忙狀態(tài)數(shù)據(jù)就會丟。所以是“快”還是“穩(wěn)”得跟設(shè)備固件開發(fā)者提前溝通好。我遇到過一個設(shè)備每 50ms 收一條指令用 WithResponse 模式根本達不到這個頻率最后雙方協(xié)商改成 WithoutResponse 應(yīng)用層 CRC 校驗才把問題解決。4.2 訂閱通知Notify 的坑主要在 CCCDBLE 設(shè)備的主動上報最常見的實現(xiàn)是Notify或Indicate。兩者的區(qū)別是 Notify 發(fā)了不管Indicate 要求主機回復(fù)確認所以 Indicate 更可靠但吞吐量更低。不管是哪一種你都要在客戶端打開一個叫CCCDClient Characteristic Configuration Descriptor的開關(guān)否則設(shè)備不會給你推數(shù)據(jù)。具體到 Windows APIGattCommunicationStatus status await characteristic.WriteClientCharacteristicConfigurationDescriptorAsync( GattClientCharacteristicConfigurationDescriptorValue.Notify); if (status GattCommunicationStatus.Success) { characteristic.ValueChanged OnCharacteristicValueChanged; }ValueChanged回調(diào)里拿到的args.CharacteristicValue是一個IBuffer用DataReader讀取即可。這個 CCCD 開關(guān)是我見到新手報錯最集中的地方。癥狀是連接正常、地址正確、服務(wù)也找到了但設(shè)備就是不上報數(shù)據(jù)。原因十有八九是沒寫這個描述符。另一個原因是把Notify和Indicate選錯了如果設(shè)備只支持 Indicate你按 Notify 去寫可能返回成功但實際沒生效或者直接返回InvalidArgument需要手動用對應(yīng)枚舉值再試一次。4.3 MTU、分包與長數(shù)據(jù)BLE 的傳輸單元叫 MTUMaximum Transmission Unit。默認在 Windows 上大多是 23 字節(jié)其中有效負載只有 20 字節(jié)去掉 ATT 頭。如果你要一次發(fā)幾百字節(jié)的數(shù)據(jù)就必須面對分包問題。好消息是Windows 的BluetoothLEAdvertisementPublisher/ GATT 客戶端會自動做 MTU 協(xié)商而且WriteValueAsync在寫超過單包容量的數(shù)據(jù)時會自動拆分成多個 ATT 包只要參數(shù)里用GattWriteOption.WriteWithResponse并且數(shù)據(jù)量不超過 512 字節(jié)通常都能成功。但如果你用的是WriteWithoutResponse很多第三方設(shè)備固件并不會自動組包你需要自己按 20 字節(jié)切分并在每包之間加延時否則設(shè)備端會直接丟棄。這里給一條實測結(jié)論寫大塊數(shù)據(jù)時先用device.GetGattServicesAsync那一套拿到設(shè)備實際協(xié)商后的 MTU 并記錄下來如果沒有特殊要求就按默認 20 字節(jié)分包包間延時 20ms成功率最高。5. 幾個必須要摳的細節(jié)與踩坑合集講完主流程再集中說幾個我實際項目中反復(fù)栽跟頭的細節(jié)。這些內(nèi)容官方文檔不會主動告訴你只有做到量級足夠多的設(shè)備接入后才會暴露出來。5.1 異步與 UI 線程的糾纏WinForms 的 UI 線程不能阻塞而 BLE 的 API 全是async。你很容易寫出這樣的代碼var device BluetoothLEDevice.FromIdAsync(deviceId).GetAwaiter().GetResult();在按鈕點擊事件里這么干一旦設(shè)備響應(yīng)慢UI 直接卡死更嚴重的是可能導(dǎo)致死鎖async方法需要在 UI 線程上恢復(fù)上下文但 UI 線程又被你GetResult()阻塞住兩邊互相等程序假死。解決方案有兩個。一是全程awaitprivate async void btnConnect_Click(object sender, EventArgs e) { btnConnect.Enabled false; try { var device await BluetoothLEDevice.FromIdAsync(txtDeviceId.Text); // 后續(xù)操作 } catch (Exception ex) { MessageBox.Show(ex.Message); } finally { btnConnect.Enabled true; } }二是如果你確實需要在后臺線程同步等待結(jié)果就在調(diào)用前先await Task.Run(() ...)跳離 UI 線程但這要求你的邏輯本身不依賴 UI 控件。最保險的還是一路async到底。另外ValueChanged事件回調(diào)是在線程池線程上執(zhí)行的如果你想在事件里更新界面必須用Invoke/BeginInvoke直接賦給textBox.Text會跨線程報錯。5.2 設(shè)備枚舉與重復(fù)連接你可能會有這種需求程序啟動后自動連接上次的關(guān)聯(lián)設(shè)備。WinForms 項目通常沒有像手機那樣完整的“配對”流程你想知道系統(tǒng)里之前連過哪些 BLE 設(shè)備可以用DeviceInformation.FindAllAsync 篩選BluetoothLEDevice的接口 IDvar devices await DeviceInformation.FindAllAsync( BluetoothLEDevice.GetDeviceSelector(), new string[] { System.Devices.DeviceInstanceId });但要注意這個列表只包含已配對或已關(guān)聯(lián)的設(shè)備不是所有掃過的設(shè)備。如果設(shè)備沒在 Windows 藍牙設(shè)置里“配對”過這里大概率查不到。所以更通用的做法還是自己維護一份“最近使用的設(shè)備 ID”列表存到Setting或文本文件里下次啟動直接用。5.3 異常處理與資源釋放BLE 設(shè)備連接后如果你不再使用最好顯式釋放device?.Dispose();否則 Windows 會保持內(nèi)部句柄占用導(dǎo)致下次FromIdAsync返回同樣的連接但實際鏈路已經(jīng)斷了。這時候你可能會看到一個非常誤導(dǎo)性的現(xiàn)象設(shè)備對象拿到了狀態(tài)是 Connected但一讀數(shù)據(jù)就超時。正確姿勢是業(yè)務(wù)關(guān)閉時調(diào)用Dispose()然后置為null下次再重新FromIdAsync。異常處理也不能隨便吞。我強烈建議所有訪問 GATT 的代碼都包try/catch并且在catch里把device.ConnectionStatus打出來。很多詭異問題排查到最后其實都是設(shè)備端主動斷鏈或者超出了射頻范圍跟代碼沒關(guān)系。6. 實測性能數(shù)據(jù)與穩(wěn)定性建議最后分享一組我在實際項目里記錄的測試數(shù)據(jù)給后面要做的朋友一個參考。測試項結(jié)果備注首次掃描到設(shè)備延遲200ms ~ 2s取決于廣播間隔設(shè)備廣播間隔設(shè) 200ms 時很穩(wěn)定從掃描到 GATT 連接完成1 ~ 2s包含服務(wù)發(fā)現(xiàn)Uncached 模式稍慢特征值單次讀取50 ~ 150ms跟設(shè)備處理速度相關(guān)20 字節(jié)分包寫 100 字節(jié)約 80ms延時設(shè)為 20ms 時穩(wěn)定Notify 推送頻率最高約 50 條/秒受設(shè)備側(cè)發(fā)送間隔限制持續(xù)運行 8 小時后內(nèi)存穩(wěn)定在 80MB 內(nèi)注意清理事件訂閱避免泄漏穩(wěn)定性建議總結(jié)成三條掃描到連接之間的間隔不要拖太久。有些外設(shè)在廣播幾秒后會主動進入睡眠或停止廣播你拿到設(shè)備列表后讓用戶慢慢選結(jié)果選完了設(shè)備已經(jīng)不可連接。界面上最好在每行顯示 RSSI 信號強度并定時刷新列表移除“失聯(lián)”設(shè)備。核心邏輯務(wù)必支持重試。我寫了一套簡單的重試機制連接失敗等待 500ms 重試最多三次讀取失敗等待 200ms 重試一次。這比用更高的設(shè)備廣播頻率管用多了。日志要記錄 Metro 級別信息。包括bluetoothAddress、deviceId、additionalData哪天現(xiàn)場出問題沒有日志你將有口難言。在我實際做的幾個產(chǎn)線工具和健康監(jiān)測 Demo 里這套 Windows BLE .NET WinForms 的方案配合上面這些細節(jié)處理穩(wěn)定性已經(jīng)夠用了。如果你也是第一次在 Windows 上折騰 BLE希望這些趟過的坑能幫你省下幾個加班的夜晚。本文還有配套的精品資源點擊獲取