效排查：Shell_NotifyIcon字段與系統(tǒng)策略)
托盤圖標(biāo)出現(xiàn)在任務(wù)欄右下角右鍵菜單響應(yīng)正常雙擊也能喚出主窗口唯獨(dú)調(diào)Shell_NotifyIcon發(fā)出去的那個(gè)氣球通知屏幕上一點(diǎn)動(dòng)靜都沒(méi)有——而且返回值還是TRUE。這個(gè)現(xiàn)象我前后遇到過(guò)三四回每次根因都不一樣有一次是uFlags漏了NIF_INFO有一次是程序被改成后臺(tái)常駐方式導(dǎo)致圖標(biāo)壓根沒(méi)掛到 explorer 上還有一次是測(cè)試機(jī)上把通知和操作的總開(kāi)關(guān)關(guān)掉了。所以看到氣球通知無(wú)效這種描述先別急著翻代碼得先把無(wú)效這兩個(gè)字拆開(kāi)判斷它到底屬于哪一類。這篇是寫(xiě)給正在做 Windows 桌面端常駐托盤程序的人看的以 CWin32為主順帶把 C#WinForms和 WPF 封裝層上的等價(jià)坑一起擺出來(lái)。讀完至少能做到兩件事一是清楚Shell_NotifyIcon發(fā)氣泡時(shí)到底是哪幾個(gè)字段在起作用二是手上有一套能自己往下查的鏈路而不是對(duì)著屏幕干瞪眼改參數(shù)。氣球通知這東西看著只有幾行 API實(shí)際上牽扯到結(jié)構(gòu)體版本、字符集、窗口消息循環(huán)、系統(tǒng)通知策略、會(huì)話隔離五個(gè)層面任何一層出問(wèn)題表現(xiàn)都是沒(méi)反應(yīng)所以分層定位比試錯(cuò)重要得多。1. 三種不彈故障點(diǎn)完全不同1.1 圖標(biāo)壓根沒(méi)進(jìn)托盤區(qū)這是最容易被跳過(guò)的一步。很多人在排查氣泡的時(shí)候默認(rèn)圖標(biāo)都在那兒了肯定是氣泡的問(wèn)題但實(shí)際情況里圖標(biāo)顯示正常并不代表NIM_ADD成功過(guò)——有一種情況是圖標(biāo)顯示出來(lái)了但那是上一次進(jìn)程殘留的僵尸圖標(biāo)鼠標(biāo)劃過(guò)就消失點(diǎn)它也沒(méi)反應(yīng)。真正判斷圖標(biāo)是否屬于當(dāng)前進(jìn)程最簡(jiǎn)單的辦法是把鼠標(biāo)懸停在圖標(biāo)上看szTip里設(shè)置的提示文字有沒(méi)有出現(xiàn)如果提示文字是空白的或者顯示的是別的程序的文字那基本可以確定當(dāng)前進(jìn)程根本沒(méi)加上圖標(biāo)氣泡自然無(wú)從談起。NIM_ADD失敗的原因里hIcon為空是最常見(jiàn)的一個(gè)。Win32 里常見(jiàn)寫(xiě)法是先LoadIcon或者LoadImage拿一個(gè)HICON再填進(jìn)nid.hIcon。這里有個(gè)真實(shí)存在的坑如果這個(gè)HICON是通過(guò)CreateIconIndirect、CopyIcon這類函數(shù)動(dòng)態(tài)生成的而代碼里又在NIM_ADD之后順手調(diào)了DestroyIcon托盤圖標(biāo)會(huì)立刻變成一塊空白或者花屏。原因是 shell 并沒(méi)有把圖標(biāo)數(shù)據(jù)拷貝走它只是持有了這個(gè)句柄你銷毀了它那邊就指向了一塊已經(jīng)失效的內(nèi)存。正確的釋放時(shí)機(jī)是NIM_DELETE之后再DestroyIcon順序不能反。還有一種更隱蔽的程序被注冊(cè)成了服務(wù)或者用計(jì)劃任務(wù)以不管用戶是否登錄都運(yùn)行的方式啟動(dòng)。這種進(jìn)程運(yùn)行在會(huì)話 0Session 0而會(huì)話 0 是沒(méi)有交互式桌面的Shell_NotifyIcon可能返回成功圖標(biāo)卻永遠(yuǎn)不可能出現(xiàn)在用戶眼前。判斷方法很簡(jiǎn)單任務(wù)管理器里看這個(gè)進(jìn)程屬于哪個(gè)會(huì)話如果不是當(dāng)前登錄用戶的會(huì)話號(hào)那所有 UI 相關(guān)的 API 都是白搭。另外提一句Windows 11 的托盤區(qū)把默認(rèn)圖標(biāo)折疊進(jìn)了溢出面板用戶不點(diǎn)開(kāi)小箭頭是看不到的。這不是故障但排查時(shí)容易被誤判成圖標(biāo)沒(méi)加進(jìn)去先確認(rèn)一下托盤設(shè)置里的隱藏的圖標(biāo)菜單。1.2 圖標(biāo)在氣泡死活不出來(lái)這一類才是標(biāo)題里說(shuō)的情況。此時(shí)NIM_ADD是成功的szTip能正常顯示右鍵菜單也能彈唯獨(dú)氣泡不出來(lái)。常見(jiàn)原因按出現(xiàn)頻率排下來(lái)大概是uFlags沒(méi)帶NIF_INFO、NIM_MODIFY之前圖標(biāo)狀態(tài)已經(jīng)丟了、szInfo為空字符串、系統(tǒng)通知開(kāi)關(guān)被關(guān)閉、發(fā)送氣泡時(shí)消息循環(huán)處于阻塞狀態(tài)。uFlags這個(gè)問(wèn)題我在代碼評(píng)審里見(jiàn)過(guò)不止一次。有人寫(xiě)了一個(gè)UpdateTrayIcon()函數(shù)把NIF_ICON | NIF_MESSAGE | NIF_TIP全填上然后在這個(gè)函數(shù)末尾順手填了szInfo和szInfoTitle以為這樣氣泡就會(huì)跟著圖標(biāo)一起更新。實(shí)際上Shell_NotifyIcon是嚴(yán)格按uFlags位掩碼來(lái)決定讀哪些字段的沒(méi)置NIF_INFO位szInfo那一段內(nèi)存它連看都不看。同理dwInfoFlags的圖標(biāo)類型、NIIF_NOSOUND這類標(biāo)志也都只在NIF_INFO置位時(shí)才生效。還有一種是先刪后沒(méi)加。某些程序在響應(yīng)WM_ENDSESSION或者顯示器的WM_DISPLAYCHANGE時(shí)會(huì)先NIM_DELETE再重新NIM_ADD如果中間某次NIM_ADD因?yàn)榇翱诰浔鸁o(wú)效而失敗后續(xù)的NIM_MODIFY就會(huì)一直返回失敗氣泡當(dāng)然也發(fā)不出來(lái)。所以我習(xí)慣把是否已添加做成一個(gè)顯式的狀態(tài)位任何一次NIM_ADD失敗都要記錄下來(lái)后續(xù)發(fā)氣泡前先檢查這個(gè)狀態(tài)。1.3 氣泡彈了但標(biāo)題是空的或者全是亂碼嚴(yán)格來(lái)說(shuō)這不算無(wú)效但它經(jīng)常和無(wú)效混為一談因?yàn)橛脩艨吹揭黄綁K或者空白會(huì)直接反饋通知沒(méi)顯示。亂碼的根因幾乎只有一個(gè)結(jié)構(gòu)體用了 ANSI 版本而字符串傳的是寬字符或者反過(guò)來(lái)。NOTIFYICONDATA在 SDK 頭文件里是通過(guò)UNICODE宏展開(kāi)成NOTIFYICONDATAW或NOTIFYICONDATAA的如果工程屬性里的字符集是使用多字節(jié)字符集而你代碼里寫(xiě)的是L...編譯器要么報(bào)錯(cuò)要么悄悄截?cái)嘧罱KszInfo里只有一個(gè)字符加個(gè)結(jié)尾。這個(gè)坑在遷移老項(xiàng)目時(shí)特別容易踩到。老工程當(dāng)年是 MBCS后來(lái)為了支持多語(yǔ)言整體改成 Unicode結(jié)果某個(gè)自己封裝的托盤類里還留著char緩沖區(qū)和新結(jié)構(gòu)體拼接編譯能過(guò)跑起來(lái)就是亂碼。定位辦法是直接看sizeof(NOTIFYICONDATA)的值Unicode 版本在 x64 下大概是 976 字節(jié)這個(gè)量級(jí)如果在調(diào)試器里看到cbSize明顯偏小那基本就是字符集或者結(jié)構(gòu)體定義對(duì)不上。2. NOTIFYICONDATA 里決定氣泡生死的字段2.1 uFlags、szInfo、szInfoTitle 三者的聯(lián)動(dòng)關(guān)系先把一段能用的代碼擺出來(lái)后面所有的討論都圍繞它展開(kāi)。下面這段是添加圖標(biāo)的初始化注意uFlags里沒(méi)有NIF_INFO因?yàn)樘砑与A段不需要?dú)馀軳OTIFYICONDATA nid { 0 }; nid.cbSize sizeof(NOTIFYICONDATA); nid.hWnd hMainWnd; nid.uID IDI_TRAY; nid.uFlags NIF_ICON | NIF_MESSAGE | NIF_TIP; nid.uCallbackMessage WM_TRAY_CALLBACK; nid.hIcon hTrayIcon; StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L常駐托盤工具); if (!Shell_NotifyIcon(NIM_ADD, nid)) { // 這里一定要留日志后面排查全靠它 }發(fā)氣泡是另一段獨(dú)立邏輯uFlags只保留NIF_INFObool ShowBalloon(HWND hWnd, UINT id, const wchar_t* title, const wchar_t* text, DWORD infoFlags) { NOTIFYICONDATA nid { 0 }; nid.cbSize sizeof(NOTIFYICONDATA); nid.hWnd hWnd; nid.uID id; nid.uFlags NIF_INFO; nid.dwInfoFlags infoFlags; StringCchCopy(nid.szInfoTitle, ARRAYSIZE(nid.szInfoTitle), title); StringCchCopy(nid.szInfo, ARRAYSIZE(nid.szInfo), text); return Shell_NotifyIcon(NIM_MODIFY, nid) ! FALSE; }這里有兩個(gè)細(xì)節(jié)值得說(shuō)。第一NIM_MODIFY階段uFlags只寫(xiě)NIF_INFO是完全正確的語(yǔ)義是這次我只改氣泡部分其它字段別動(dòng)不需要把NIF_ICON再寫(xiě)一遍。第二szInfo傳空字符串注意不是空指針是長(zhǎng)度為 0 的字符串的語(yǔ)義是移除當(dāng)前顯示的氣泡不是什么都不做。有些代碼在錯(cuò)誤分支里填了個(gè)空字符串當(dāng)兜底結(jié)果就是看起來(lái)什么都沒(méi)發(fā)生。字段長(zhǎng)度也有硬上限szInfo是 256 個(gè)WCHARszInfoTitle是 64 個(gè)WCHAR都包含結(jié)尾的空字符。超長(zhǎng)會(huì)被截?cái)嘤肧tringCchCopy這類安全函數(shù)能保證不出界但內(nèi)容確實(shí)會(huì)丟。我見(jiàn)過(guò)標(biāo)題寫(xiě)了一長(zhǎng)串路徑導(dǎo)致后面全被切掉的看起來(lái)像標(biāo)題顯示不全其實(shí)是長(zhǎng)度超限。2.2 cbSize、uVersion 與那個(gè)共用體的歷史包袱cbSize是所有NOTIFYICONDATA故障里最隱蔽的一個(gè)。這個(gè)字段的用途是讓 shell 知道調(diào)用方用的是哪個(gè)版本的結(jié)構(gòu)體因?yàn)閺?Windows 2000 到現(xiàn)在這個(gè)結(jié)構(gòu)體加過(guò)好幾輪字段。寫(xiě)sizeof(NOTIFYICONDATA)在正常情況下永遠(yuǎn)是對(duì)的問(wèn)題出在兩種場(chǎng)景一是工程引用了很老的第三方 SDK 頭文件結(jié)構(gòu)體定義本身就缺字段sizeof算出來(lái)偏小二是用 C# 或其它語(yǔ)言手工定義StructLayout時(shí)字段漏了或者順序錯(cuò)了。第二種場(chǎng)景我踩過(guò)。C# 里為了不依賴 WinForms 的NotifyIcon有人會(huì)自己DllImport一個(gè)Shell_NotifyIcon然后手寫(xiě)一個(gè)NOTIFYICONDATA結(jié)構(gòu)體。少寫(xiě)一個(gè)guidItem或者把uTimeout的位置寫(xiě)錯(cuò)編譯一點(diǎn)問(wèn)題沒(méi)有運(yùn)行起來(lái)cbSize對(duì)不上NIM_ADD直接返回FALSE。這種情況在調(diào)試器里看一眼cbSize和預(yù)期值差多少基本就能定位。再說(shuō)uVersion。NOTIFYICONDATA里uTimeout和uVersion是共用同一塊內(nèi)存的union { UINT uTimeout; UINT uVersion; };也就是說(shuō)你不能在同一次調(diào)用里既設(shè)超時(shí)又設(shè)版本號(hào)。設(shè)置版本要用NIM_SETVERSION把uVersion填成NOTIFYICON_VERSION_4這個(gè)動(dòng)作會(huì)改變后續(xù)回調(diào)消息的編碼方式——lParam的低字是消息 ID高字是圖標(biāo) ID。很多人加了NIM_SETVERSION之后發(fā)現(xiàn)右鍵菜單不彈了就是因?yàn)榛卣{(diào)處理還在按老格式解析lParam。所以這條命令不是加了更好而是加了就得改回調(diào)。NOTIFYICON_VERSION_4還有另一個(gè)副作用uTimeout被徹底忽略氣泡停留時(shí)長(zhǎng)完全由系統(tǒng)的輔助功能設(shè)置決定。如果你有代碼依賴精確控制氣泡顯示 3 秒還是 10 秒那在 v4 下是做不到的。2.3 dwInfoFlags 里幾個(gè)會(huì)反向生效的標(biāo)志dwInfoFlags決定氣泡左側(cè)那個(gè)小圖標(biāo)的樣式常見(jiàn)取值是NIIF_NONE、NIIF_INFO、NIIF_WARNING、NIIF_ERROR、NIIF_USER。前四個(gè)都是系統(tǒng)內(nèi)置圖標(biāo)直接寫(xiě)就行NIIF_USER則需要額外配合hBalloonIcon字段。這里有個(gè)真實(shí)的坑NIIF_USER置位但hBalloonIcon留空時(shí)不同 Windows 版本的處理不一致有的版本回退到hIcon有的版本干脆畫(huà)一個(gè)默認(rèn)圖標(biāo)還有的版本會(huì)導(dǎo)致整個(gè)氣泡不顯示。我現(xiàn)在的做法是要么不用NIIF_USER用就老老實(shí)實(shí)把hBalloonIcon填上別指望系統(tǒng)幫你兜底。另一個(gè)有意思的標(biāo)志是NIIF_RESPECT_QUIET_TIMEWindows 7 引入的。置位之后如果系統(tǒng)處于安靜時(shí)間現(xiàn)在叫專注助手這條氣泡會(huì)被直接丟棄不是延遲顯示是丟棄。這個(gè)標(biāo)志的設(shè)計(jì)初衷是尊重用戶不想被打擾的意愿但如果你的程序發(fā)的是關(guān)鍵提醒置了這個(gè)位就等于主動(dòng)放棄了顯示機(jī)會(huì)。反過(guò)來(lái)如果你不置這個(gè)位系統(tǒng)在某些版本上仍然會(huì)按全局策略抑制橫幅——這一點(diǎn)各版本行為不完全一致所以不要用它來(lái)做能不能顯示的開(kāi)關(guān)。NIIF_NOSOUND相對(duì)簡(jiǎn)單加上就不響提示音。有個(gè)細(xì)節(jié)是它不影響氣泡本身的顯示只影響聲音所以別把它和靜音模式下氣泡不顯示混為一談。3. 代碼沒(méi)問(wèn)題但屏幕沒(méi)反應(yīng)系統(tǒng)層攔在哪3.1 通知總開(kāi)關(guān)、專注助手與安靜時(shí)間這是排查時(shí)最容易漏掉的一層因?yàn)樗辉谀愕拇a里而在用戶的機(jī)器上。Windows 10 之后系統(tǒng)設(shè)置里有一個(gè)通知和操作的總開(kāi)關(guān)關(guān)掉之后所有應(yīng)用的通知全部靜默下面還有按應(yīng)用細(xì)分的開(kāi)關(guān)以及專注助手的幾種模式關(guān)閉、僅優(yōu)先通知、僅鬧鐘。Shell_NotifyIcon發(fā)出的氣泡在 Windows 8 之后已經(jīng)被系統(tǒng)當(dāng)作通知來(lái)管理了所以它會(huì)完整地受這些開(kāi)關(guān)影響。表現(xiàn)是Shell_NotifyIcon返回TRUE氣泡不出現(xiàn)通知中心里也找不到。這種情況你改一萬(wàn)行代碼都沒(méi)用。排查手段是讓測(cè)試機(jī)恢復(fù)到默認(rèn)狀態(tài)通知總開(kāi)關(guān)打開(kāi)、專注助手關(guān)閉、當(dāng)前應(yīng)用在通知列表里處于允許狀態(tài)。還有一點(diǎn)如果程序以管理員權(quán)限運(yùn)行而系統(tǒng)設(shè)置里的通知是按應(yīng)用配置的某些版本下管理員進(jìn)程的通知配置和普通進(jìn)程不是同一份表現(xiàn)就是普通權(quán)限下能彈、提權(quán)后不彈。這個(gè)差異在不同系統(tǒng)版本上表現(xiàn)不一致我的做法是測(cè)試矩陣?yán)锕潭ò胀?quán)限和管理員權(quán)限兩行別只測(cè)一種。老系統(tǒng)上還有一個(gè)注冊(cè)表開(kāi)關(guān)HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced下的EnableBalloonTips值為 0 時(shí)禁用氣球提示。這個(gè)鍵在新系統(tǒng)上是否仍然生效取決于版本但在 Windows 7 時(shí)代它是標(biāo)準(zhǔn)的關(guān)閉方式排查老環(huán)境時(shí)值得看一眼。組策略里也有對(duì)應(yīng)的關(guān)閉通知?dú)馇蛱崾卷?xiàng)域環(huán)境下的機(jī)器可能被統(tǒng)一下發(fā)。3.2 會(huì)話與用戶身份Session 0 和 RunAs 的死角前面提過(guò)會(huì)話 0 的問(wèn)題這里展開(kāi)說(shuō)。Windows 的服務(wù)宿主機(jī)制決定了服務(wù)進(jìn)程運(yùn)行在會(huì)話 0那是一個(gè)沒(méi)有交互式桌面的獨(dú)立會(huì)話。任何在會(huì)話 0 里調(diào)用的 UI 相關(guān) API包括Shell_NotifyIcon、MessageBox、CreateWindow要么失敗要么創(chuàng)建一個(gè)用戶永遠(yuǎn)看不到的窗口。這個(gè)問(wèn)題在實(shí)際項(xiàng)目里通常表現(xiàn)為開(kāi)發(fā)機(jī)上好好的裝到客戶機(jī)上就沒(méi)通知。區(qū)別在于開(kāi)發(fā)機(jī)是雙擊 exe 運(yùn)行的客戶機(jī)上是通過(guò)服務(wù)或者計(jì)劃任務(wù)啟動(dòng)的。定位方法是在任務(wù)管理器里加一列會(huì)話 ID看進(jìn)程對(duì)應(yīng)的數(shù)字是不是和當(dāng)前登錄用戶一致。如果不一致那問(wèn)題不在代碼在于部署方式——要么改成用戶登錄后自啟動(dòng)要么用會(huì)話隔離機(jī)制把 UI 部分拆成一個(gè)運(yùn)行在用戶會(huì)話里的獨(dú)立進(jìn)程。還有一種情況是以另一個(gè)用戶身份運(yùn)行比如右鍵以其他用戶身份運(yùn)行或者用憑據(jù)管理器啟動(dòng)。這時(shí)圖標(biāo)會(huì)加到那個(gè)用戶的托盤里當(dāng)前登錄用戶看不到但那個(gè)用戶如果同時(shí)在線快速用戶切換在他自己的桌面里是能看到圖標(biāo)的?，F(xiàn)象就是我這邊沒(méi)圖標(biāo)但換個(gè)賬號(hào)登錄就有了很容易被誤判成偶發(fā) bug。3.3 Windows 8 之后氣球改頭換面成 Toast這條屬于知道就行不知道會(huì)繞遠(yuǎn)路的范疇。從 Windows 8 開(kāi)始Shell_NotifyIcon發(fā)出的氣球通知在視覺(jué)上已經(jīng)變成了 toast 樣式——從屏幕右下角滑入、停留幾秒、然后收進(jìn)通知中心。接口沒(méi)變樣式變了。這個(gè)變化帶來(lái)兩個(gè)實(shí)際影響。第一通知中心會(huì)成為這些氣泡的歸檔地用戶在通知中心里能看到歷史消息這意味著重復(fù)發(fā)同一條消息的行為和老系統(tǒng)不一樣了老系統(tǒng)上重復(fù)發(fā)會(huì)不斷彈新的新系統(tǒng)上可能出現(xiàn)合并或者覆蓋。第二某些系統(tǒng)版本上如果程序沒(méi)有設(shè)置AppUserModelID通知在系統(tǒng)里的歸屬會(huì)是一個(gè)默認(rèn)的宿主表現(xiàn)是通知列表里看不到你的應(yīng)用名用戶在設(shè)置里想允許你的通知都找不到對(duì)應(yīng)條目。設(shè)置AppUserModelID的 API 是SetCurrentProcessExplicitAppUserModelID在進(jìn)程啟動(dòng)早期調(diào)用。如果對(duì)通知的可靠性要求比較高其實(shí)可以考慮直接走 Toast 通知那套接口代價(jià)是需要注冊(cè)快捷方式、需要處理激活回調(diào)工程復(fù)雜度上一個(gè)臺(tái)階。托盤氣球勝在簡(jiǎn)單二十行代碼就能跑Toast 勝在可控能拿到點(diǎn)擊、能進(jìn)通知中心歸檔、能被用戶精細(xì)管理。選哪個(gè)取決于你的通知是順手提示一下還是業(yè)務(wù)流程的一環(huán)。4. 一條能自己走完的排查鏈路4.1 用三十行最小工程把業(yè)務(wù)代碼摘出去我處理這類問(wèn)題的固定第一步是新建一個(gè)空的 Win32 工程只保留一個(gè)隱藏主窗口、一個(gè)托盤圖標(biāo)、一個(gè)定時(shí)器定時(shí)器每三秒發(fā)一次氣泡。這個(gè)工程大概三十行寫(xiě)完不超過(guò)十分鐘。之所以要先做這一步是因?yàn)樵谡鎸?shí)項(xiàng)目里氣泡不顯示可能是業(yè)務(wù)邏輯、線程調(diào)度、窗口生命周期三者疊加出來(lái)的你直接在里面改參數(shù)改一次跑一次變量太多判斷不了哪個(gè)改動(dòng)起了作用。最小工程的骨架大致是這樣LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_CREATE: AddTrayIcon(hWnd); SetTimer(hWnd, TIMER_BALLOON, 3000, nullptr); return 0; case WM_TIMER: if (wParam TIMER_BALLOON) { ShowBalloon(hWnd, IDI_TRAY, L測(cè)試標(biāo)題, L這是一條測(cè)試氣泡, NIIF_INFO); } return 0; case WM_DESTROY: RemoveTrayIcon(hWnd); PostQuitMessage(0); return 0; } return DefWindowProc(hWnd, msg, wParam, lParam); }如果這個(gè)最小工程能彈氣泡說(shuō)明 API 用法和系統(tǒng)環(huán)境都沒(méi)問(wèn)題問(wèn)題在你的業(yè)務(wù)代碼里如果彈不出來(lái)說(shuō)明問(wèn)題在環(huán)境或者調(diào)用方式上接下來(lái)往系統(tǒng)層查。這一步能省掉一半的排查時(shí)間。4.2 返回值、窗口消息、監(jiān)視工具三處取證最小工程也不彈的時(shí)候取證要分三路走。第一路看返回值。Shell_NotifyIcon返回FALSE說(shuō)明 shell 明確拒絕了這時(shí)基本可以鎖定字段錯(cuò)誤cbSize不對(duì)、hWnd無(wú)效、uID沖突。返回TRUE但無(wú)顯示說(shuō)明接收端沒(méi)問(wèn)題問(wèn)題在展示端系統(tǒng)策略、會(huì)話、桌面可見(jiàn)性。這兩條分支的排查方向完全相反所以返回值必須看。第二路看窗口消息。如果要做氣泡點(diǎn)擊響應(yīng)uCallbackMessage指定的消息會(huì)在氣泡被點(diǎn)擊時(shí)發(fā)到你的窗口。用一個(gè)能抓窗口消息的工具掛在目標(biāo)窗口上觀察發(fā)氣泡前后有沒(méi)有WM_USER范圍內(nèi)的消息流動(dòng)。這一步主要是確認(rèn) shell 到底有沒(méi)有收到請(qǐng)求。第三路看系統(tǒng)狀態(tài)。通知設(shè)置、專注助手、會(huì)話 ID、是否提權(quán)這四項(xiàng)各花一分鐘確認(rèn)比讀一天文檔有用。我現(xiàn)在的習(xí)慣是在程序的關(guān)于頁(yè)面里放一個(gè)隱藏的診斷入口一鍵打印這幾項(xiàng)狀態(tài)客戶反饋問(wèn)題時(shí)讓他截個(gè)圖能省掉好幾輪來(lái)回?，F(xiàn)象優(yōu)先懷疑驗(yàn)證方式NIM_ADD返回 FALSEcbSize、hIcon為空、窗口句柄無(wú)效調(diào)試器里看cbSize與sizeof是否一致圖標(biāo)在氣泡無(wú)返回值 TRUEuFlags漏NIF_INFO斷點(diǎn)檢查發(fā)送時(shí)的uFlags值圖標(biāo)不在氣泡無(wú)會(huì)話 0、圖標(biāo)句柄被提前釋放任務(wù)管理器看會(huì)話 ID檢查DestroyIcon時(shí)機(jī)氣泡出但標(biāo)題空白字符集不匹配看sizeof(NOTIFYICONDATA)與工程字符集設(shè)置時(shí)好時(shí)壞消息循環(huán)被阻塞、定時(shí)器被搶占檢查主線程是否有長(zhǎng)耗時(shí)同步操作特定機(jī)器必現(xiàn)通知開(kāi)關(guān)、專注助手、組策略重置通知設(shè)置為默認(rèn)后復(fù)測(cè)4.3 把什么時(shí)候不彈記錄成日志這一點(diǎn)聽(tīng)起來(lái)平淡但它決定了后續(xù)排查是幾天還是幾小時(shí)。我在托盤模塊里加了一組固定的日志點(diǎn)NIM_ADD的結(jié)果、NIM_DELETE的結(jié)果、每次發(fā)氣泡前的uFlags和dwInfoFlags值、發(fā)氣泡的返回值、當(dāng)前進(jìn)程的會(huì)話 ID 和是否提權(quán)。這些信息加起來(lái)不到二十行代碼但客戶現(xiàn)場(chǎng)出問(wèn)題時(shí)看一眼日志就能把范圍縮小到一兩個(gè)方向。有個(gè)細(xì)節(jié)日志里不要把szInfo全文打進(jìn)去用戶數(shù)據(jù)可能很長(zhǎng)也可能包含不該落盤的內(nèi)容打個(gè)長(zhǎng)度和標(biāo)題就夠了。5. 托管封裝層WinForms 與 WPF 的等價(jià)坑5.1 NotifyIcon.ShowBalloonTip 的前置條件C# 的 WinForms 里NotifyIcon類把Shell_NotifyIcon包了一層接口看著簡(jiǎn)單坑一樣不少。ShowBalloonTip(int timeout)要能生效至少得滿足三個(gè)條件Visible為true、Icon不為null、圖標(biāo)已經(jīng)被系統(tǒng)接受。第一個(gè)條件是硬性的Visible false時(shí)調(diào)ShowBalloonTip不拋異常也不顯示最容易漏。第二個(gè)條件很多人以為只要給Icon賦值就行實(shí)際上如果你是從資源文件動(dòng)態(tài)加載圖標(biāo)流用完順手把StreamDispose掉了Icon對(duì)象的內(nèi)部句柄可能已經(jīng)失效表現(xiàn)就是托盤圖標(biāo)顯示成一塊空白氣泡也跟著不顯示。第三個(gè)條件在窗體生命周期早期容易出問(wèn)題。在Form_Load里立刻調(diào)ShowBalloonTip有些機(jī)器上不生效因?yàn)檫@時(shí)窗口句柄剛創(chuàng)建托盤圖標(biāo)還沒(méi)真正掛上去。穩(wěn)妥做法是Load之后用BeginInvoke推遲到消息隊(duì)列下一輪再調(diào)或者在Shown事件里調(diào)。timeout參數(shù)在 Vista 之后基本被忽略了實(shí)際時(shí)長(zhǎng)由系統(tǒng)的輔助功能設(shè)置決定。這一點(diǎn)和老系統(tǒng)不一樣如果產(chǎn)品文檔里寫(xiě)了氣泡顯示 5 秒最好改成約 5 秒實(shí)際由系統(tǒng)設(shè)置決定免得后面被當(dāng)成 bug 提。5.2 消息泵被堵住時(shí)氣泡會(huì)遲到Shell_NotifyIcon內(nèi)部是通過(guò)窗口消息和任務(wù)欄通信的這意味著它依賴調(diào)用線程的消息循環(huán)。如果主線程正在跑一個(gè)長(zhǎng)耗時(shí)同步任務(wù)比如讀一個(gè)大文件、等一個(gè)網(wǎng)絡(luò)請(qǐng)求、跑一段密集計(jì)算那么即使你在另一個(gè)線程里調(diào)ShowBalloonTip調(diào)用也可能被卡住直到主線程的消息泵重新轉(zhuǎn)起來(lái)?，F(xiàn)象很有迷惑性日志顯示已發(fā)送氣泡但用戶是在幾秒甚至幾十秒之后才看到或者干脆看不到因?yàn)橐呀?jīng)過(guò)了時(shí)效。這類問(wèn)題在后臺(tái)任務(wù)完成時(shí)彈通知的場(chǎng)景里特別常見(jiàn)因?yàn)楹笈_(tái)任務(wù)完成的時(shí)刻主線程往往正在刷新界面。處理辦法是有的把耗時(shí)任務(wù)放到后臺(tái)線程主線程只負(fù)責(zé) UI或者在不依賴NotifyIcon對(duì)象的場(chǎng)景下用一個(gè)獨(dú)立的隱藏窗口在自己的線程里跑消息循環(huán)來(lái)處理托盤消息。后者工程量大些但如果托盤邏輯要脫離主窗口獨(dú)立存活比如主窗口可以關(guān)閉但程序不退出這個(gè)結(jié)構(gòu)反而更清晰。WPF 這邊沒(méi)有內(nèi)置的托盤圖標(biāo)控件社區(qū)里常見(jiàn)的做法是引用 WinForms 的NotifyIcon或者用第三方庫(kù)。第三方庫(kù)如果自己實(shí)現(xiàn)了Shell_NotifyIcon的互操作那前面說(shuō)的cbSize、uFlags、字符集三件事依然適用換語(yǔ)言不換原理。選庫(kù)的時(shí)候可以看一眼它有沒(méi)有處理NOTIFYICON_VERSION_4沒(méi)處理的話右鍵菜單的坐標(biāo)計(jì)算在某些機(jī)器上會(huì)偏。6. 把這套東西做成不容易再出問(wèn)題的結(jié)構(gòu)6.1 用一個(gè)帶狀態(tài)位的發(fā)送函數(shù)收口在項(xiàng)目里我最后的做法是把托盤的添加刪除發(fā)氣泡三個(gè)動(dòng)作集中在一個(gè)小模塊里模塊內(nèi)部維護(hù)一個(gè)bool added狀態(tài)位任何一次NIM_ADD成功才置位NIM_DELETE后清零。發(fā)氣泡的入口函數(shù)第一件事就是檢查這個(gè)狀態(tài)位沒(méi)置位就先嘗試添加一次。這樣不管上層怎么調(diào)用都不會(huì)出現(xiàn)圖標(biāo)沒(méi)了還在發(fā)氣泡的靜默失敗。同時(shí)這個(gè)模塊對(duì)外只暴露一個(gè)ShowBalloon(title, text, level)函數(shù)level是個(gè)枚舉映射到NIIF_INFO、NIIF_WARNING、NIIF_ERROR。這樣上層不需要知道dwInfoFlags的存在后面如果要換實(shí)現(xiàn)比如換成 Toast 通知改動(dòng)面只在一個(gè)文件里。還有一個(gè)小設(shè)計(jì)發(fā)氣泡函數(shù)返回一個(gè)枚舉區(qū)分發(fā)送成功、發(fā)送失敗、系統(tǒng)策略可能抑制三種結(jié)果。第三種判斷不了那么準(zhǔn)可以根據(jù)會(huì)話 ID 和通知開(kāi)關(guān)做個(gè)粗略推斷。有這個(gè)返回值上層在做關(guān)鍵提醒時(shí)就能選擇走別的通道比如閃爍任務(wù)欄、改托盤圖標(biāo)顏色而不是把所有希望都押在氣泡上。6.2 退出時(shí)的清理和僵尸圖標(biāo)NIM_DELETE一定要在窗口銷毀之前調(diào)而且要用和NIM_ADD完全相同的hWnd和uID。我見(jiàn)過(guò)填錯(cuò)uID導(dǎo)致圖標(biāo)刪不掉的情況表現(xiàn)是程序退出后圖標(biāo)還掛在那兒鼠標(biāo)劃過(guò)才消失。這不僅僅是觀感問(wèn)題——?dú)埩舻膱D標(biāo)會(huì)占用那個(gè)uID下次啟動(dòng)如果復(fù)用同一個(gè) ID行為可能不可預(yù)期。另一個(gè)清理時(shí)機(jī)是WM_ENDSESSION系統(tǒng)關(guān)機(jī)或者注銷時(shí)程序不一定能走完正常的退出流程。在這個(gè)消息里補(bǔ)一次NIM_DELETE能減少殘留。還有崩潰場(chǎng)景進(jìn)程直接掛掉不會(huì)執(zhí)行任何清理代碼圖標(biāo)一定殘留這個(gè)沒(méi)辦法只能靠系統(tǒng)自己回收。如果程序支持多實(shí)例uID的分配要小心。兩個(gè)實(shí)例用同一個(gè)hWnd和uID是不可能的hWnd天然不同但如果用了自己生成的guidItem標(biāo)識(shí)兩個(gè)實(shí)例可能會(huì)互相覆蓋。多實(shí)例場(chǎng)景建議用單實(shí)例機(jī)制直接禁掉或者在guidItem里加入進(jìn)程相關(guān)的區(qū)分信息。6.3 版本差異下的降級(jí)策略不同 Windows 版本對(duì)氣泡的處理差異實(shí)際項(xiàng)目里沒(méi)必要逐一適配但有三條底線值得守住。第一條不要在NIM_ADD的時(shí)候一次性把NIF_INFO也帶上試圖順便彈個(gè)氣泡添加和修改分成兩次調(diào)用邏輯清晰出問(wèn)題也好定位。第二條NIM_SETVERSION只在確實(shí)需要 v4 的回調(diào)格式時(shí)才調(diào)調(diào)了就同步改回調(diào)解析邏輯兩者必須一起改。第三條uTimeout不要依賴需要多停留一會(huì)兒的需求用重復(fù)發(fā)送或者改成帶交互的通知來(lái)實(shí)現(xiàn)更好別指望這個(gè)字段。我在實(shí)際項(xiàng)目里的體會(huì)是托盤氣泡這個(gè)功能的問(wèn)題密度和代碼量完全不成比例——二十行代碼的功能可能需要幾百行的排查經(jīng)驗(yàn)來(lái)兜底。所以能把它封裝干凈就封裝干凈別讓業(yè)務(wù)邏輯直接碰NOTIFYICONDATA后面換人維護(hù)或者系統(tǒng)升級(jí)改一個(gè)文件就夠了。 Windows托盤氣球通知無(wú)效排查：Shell_NotifyIcon字段與系統(tǒng)策略
托盤圖標(biāo)出現(xiàn)在任務(wù)欄右下角右鍵菜單響應(yīng)正常雙擊也能喚出主窗口唯獨(dú)調(diào)Shell_NotifyIcon發(fā)出去的那個(gè)氣球通知屏幕上一點(diǎn)動(dòng)靜都沒(méi)有——而且返回值還是TRUE。這個(gè)現(xiàn)象我前后遇到過(guò)三四回每次根因都不一樣有一次是uFlags漏了NIF_INFO有一次是程序被改成后臺(tái)常駐方式導(dǎo)致圖標(biāo)壓根沒(méi)掛到 explorer 上還有一次是測(cè)試機(jī)上把通知和操作的總開(kāi)關(guān)關(guān)掉了。所以看到氣球通知無(wú)效這種描述先別急著翻代碼得先把無(wú)效這兩個(gè)字拆開(kāi)判斷它到底屬于哪一類。這篇是寫(xiě)給正在做 Windows 桌面端常駐托盤程序的人看的以 CWin32為主順帶把 C#WinForms和 WPF 封裝層上的等價(jià)坑一起擺出來(lái)。讀完至少能做到兩件事一是清楚Shell_NotifyIcon發(fā)氣泡時(shí)到底是哪幾個(gè)字段在起作用二是手上有一套能自己往下查的鏈路而不是對(duì)著屏幕干瞪眼改參數(shù)。氣球通知這東西看著只有幾行 API實(shí)際上牽扯到結(jié)構(gòu)體版本、字符集、窗口消息循環(huán)、系統(tǒng)通知策略、會(huì)話隔離五個(gè)層面任何一層出問(wèn)題表現(xiàn)都是沒(méi)反應(yīng)所以分層定位比試錯(cuò)重要得多。1. 三種不彈故障點(diǎn)完全不同1.1 圖標(biāo)壓根沒(méi)進(jìn)托盤區(qū)這是最容易被跳過(guò)的一步。很多人在排查氣泡的時(shí)候默認(rèn)圖標(biāo)都在那兒了肯定是氣泡的問(wèn)題但實(shí)際情況里圖標(biāo)顯示正常并不代表NIM_ADD成功過(guò)——有一種情況是圖標(biāo)顯示出來(lái)了但那是上一次進(jìn)程殘留的僵尸圖標(biāo)鼠標(biāo)劃過(guò)就消失點(diǎn)它也沒(méi)反應(yīng)。真正判斷圖標(biāo)是否屬于當(dāng)前進(jìn)程最簡(jiǎn)單的辦法是把鼠標(biāo)懸停在圖標(biāo)上看szTip里設(shè)置的提示文字有沒(méi)有出現(xiàn)如果提示文字是空白的或者顯示的是別的程序的文字那基本可以確定當(dāng)前進(jìn)程根本沒(méi)加上圖標(biāo)氣泡自然無(wú)從談起。NIM_ADD失敗的原因里hIcon為空是最常見(jiàn)的一個(gè)。Win32 里常見(jiàn)寫(xiě)法是先LoadIcon或者LoadImage拿一個(gè)HICON再填進(jìn)nid.hIcon。這里有個(gè)真實(shí)存在的坑如果這個(gè)HICON是通過(guò)CreateIconIndirect、CopyIcon這類函數(shù)動(dòng)態(tài)生成的而代碼里又在NIM_ADD之后順手調(diào)了DestroyIcon托盤圖標(biāo)會(huì)立刻變成一塊空白或者花屏。原因是 shell 并沒(méi)有把圖標(biāo)數(shù)據(jù)拷貝走它只是持有了這個(gè)句柄你銷毀了它那邊就指向了一塊已經(jīng)失效的內(nèi)存。正確的釋放時(shí)機(jī)是NIM_DELETE之后再DestroyIcon順序不能反。還有一種更隱蔽的程序被注冊(cè)成了服務(wù)或者用計(jì)劃任務(wù)以不管用戶是否登錄都運(yùn)行的方式啟動(dòng)。這種進(jìn)程運(yùn)行在會(huì)話 0Session 0而會(huì)話 0 是沒(méi)有交互式桌面的Shell_NotifyIcon可能返回成功圖標(biāo)卻永遠(yuǎn)不可能出現(xiàn)在用戶眼前。判斷方法很簡(jiǎn)單任務(wù)管理器里看這個(gè)進(jìn)程屬于哪個(gè)會(huì)話如果不是當(dāng)前登錄用戶的會(huì)話號(hào)那所有 UI 相關(guān)的 API 都是白搭。另外提一句Windows 11 的托盤區(qū)把默認(rèn)圖標(biāo)折疊進(jìn)了溢出面板用戶不點(diǎn)開(kāi)小箭頭是看不到的。這不是故障但排查時(shí)容易被誤判成圖標(biāo)沒(méi)加進(jìn)去先確認(rèn)一下托盤設(shè)置里的隱藏的圖標(biāo)菜單。1.2 圖標(biāo)在氣泡死活不出來(lái)這一類才是標(biāo)題里說(shuō)的情況。此時(shí)NIM_ADD是成功的szTip能正常顯示右鍵菜單也能彈唯獨(dú)氣泡不出來(lái)。常見(jiàn)原因按出現(xiàn)頻率排下來(lái)大概是uFlags沒(méi)帶NIF_INFO、NIM_MODIFY之前圖標(biāo)狀態(tài)已經(jīng)丟了、szInfo為空字符串、系統(tǒng)通知開(kāi)關(guān)被關(guān)閉、發(fā)送氣泡時(shí)消息循環(huán)處于阻塞狀態(tài)。uFlags這個(gè)問(wèn)題我在代碼評(píng)審里見(jiàn)過(guò)不止一次。有人寫(xiě)了一個(gè)UpdateTrayIcon()函數(shù)把NIF_ICON | NIF_MESSAGE | NIF_TIP全填上然后在這個(gè)函數(shù)末尾順手填了szInfo和szInfoTitle以為這樣氣泡就會(huì)跟著圖標(biāo)一起更新。實(shí)際上Shell_NotifyIcon是嚴(yán)格按uFlags位掩碼來(lái)決定讀哪些字段的沒(méi)置NIF_INFO位szInfo那一段內(nèi)存它連看都不看。同理dwInfoFlags的圖標(biāo)類型、NIIF_NOSOUND這類標(biāo)志也都只在NIF_INFO置位時(shí)才生效。還有一種是先刪后沒(méi)加。某些程序在響應(yīng)WM_ENDSESSION或者顯示器的WM_DISPLAYCHANGE時(shí)會(huì)先NIM_DELETE再重新NIM_ADD如果中間某次NIM_ADD因?yàn)榇翱诰浔鸁o(wú)效而失敗后續(xù)的NIM_MODIFY就會(huì)一直返回失敗氣泡當(dāng)然也發(fā)不出來(lái)。所以我習(xí)慣把是否已添加做成一個(gè)顯式的狀態(tài)位任何一次NIM_ADD失敗都要記錄下來(lái)后續(xù)發(fā)氣泡前先檢查這個(gè)狀態(tài)。1.3 氣泡彈了但標(biāo)題是空的或者全是亂碼嚴(yán)格來(lái)說(shuō)這不算無(wú)效但它經(jīng)常和無(wú)效混為一談因?yàn)橛脩艨吹揭黄綁K或者空白會(huì)直接反饋通知沒(méi)顯示。亂碼的根因幾乎只有一個(gè)結(jié)構(gòu)體用了 ANSI 版本而字符串傳的是寬字符或者反過(guò)來(lái)。NOTIFYICONDATA在 SDK 頭文件里是通過(guò)UNICODE宏展開(kāi)成NOTIFYICONDATAW或NOTIFYICONDATAA的如果工程屬性里的字符集是使用多字節(jié)字符集而你代碼里寫(xiě)的是L...編譯器要么報(bào)錯(cuò)要么悄悄截?cái)嘧罱KszInfo里只有一個(gè)字符加個(gè)結(jié)尾。這個(gè)坑在遷移老項(xiàng)目時(shí)特別容易踩到。老工程當(dāng)年是 MBCS后來(lái)為了支持多語(yǔ)言整體改成 Unicode結(jié)果某個(gè)自己封裝的托盤類里還留著char緩沖區(qū)和新結(jié)構(gòu)體拼接編譯能過(guò)跑起來(lái)就是亂碼。定位辦法是直接看sizeof(NOTIFYICONDATA)的值Unicode 版本在 x64 下大概是 976 字節(jié)這個(gè)量級(jí)如果在調(diào)試器里看到cbSize明顯偏小那基本就是字符集或者結(jié)構(gòu)體定義對(duì)不上。2. NOTIFYICONDATA 里決定氣泡生死的字段2.1 uFlags、szInfo、szInfoTitle 三者的聯(lián)動(dòng)關(guān)系先把一段能用的代碼擺出來(lái)后面所有的討論都圍繞它展開(kāi)。下面這段是添加圖標(biāo)的初始化注意uFlags里沒(méi)有NIF_INFO因?yàn)樘砑与A段不需要?dú)馀軳OTIFYICONDATA nid { 0 }; nid.cbSize sizeof(NOTIFYICONDATA); nid.hWnd hMainWnd; nid.uID IDI_TRAY; nid.uFlags NIF_ICON | NIF_MESSAGE | NIF_TIP; nid.uCallbackMessage WM_TRAY_CALLBACK; nid.hIcon hTrayIcon; StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L常駐托盤工具); if (!Shell_NotifyIcon(NIM_ADD, nid)) { // 這里一定要留日志后面排查全靠它 }發(fā)氣泡是另一段獨(dú)立邏輯uFlags只保留NIF_INFObool ShowBalloon(HWND hWnd, UINT id, const wchar_t* title, const wchar_t* text, DWORD infoFlags) { NOTIFYICONDATA nid { 0 }; nid.cbSize sizeof(NOTIFYICONDATA); nid.hWnd hWnd; nid.uID id; nid.uFlags NIF_INFO; nid.dwInfoFlags infoFlags; StringCchCopy(nid.szInfoTitle, ARRAYSIZE(nid.szInfoTitle), title); StringCchCopy(nid.szInfo, ARRAYSIZE(nid.szInfo), text); return Shell_NotifyIcon(NIM_MODIFY, nid) ! FALSE; }這里有兩個(gè)細(xì)節(jié)值得說(shuō)。第一NIM_MODIFY階段uFlags只寫(xiě)NIF_INFO是完全正確的語(yǔ)義是這次我只改氣泡部分其它字段別動(dòng)不需要把NIF_ICON再寫(xiě)一遍。第二szInfo傳空字符串注意不是空指針是長(zhǎng)度為 0 的字符串的語(yǔ)義是移除當(dāng)前顯示的氣泡不是什么都不做。有些代碼在錯(cuò)誤分支里填了個(gè)空字符串當(dāng)兜底結(jié)果就是看起來(lái)什么都沒(méi)發(fā)生。字段長(zhǎng)度也有硬上限szInfo是 256 個(gè)WCHARszInfoTitle是 64 個(gè)WCHAR都包含結(jié)尾的空字符。超長(zhǎng)會(huì)被截?cái)嘤肧tringCchCopy這類安全函數(shù)能保證不出界但內(nèi)容確實(shí)會(huì)丟。我見(jiàn)過(guò)標(biāo)題寫(xiě)了一長(zhǎng)串路徑導(dǎo)致后面全被切掉的看起來(lái)像標(biāo)題顯示不全其實(shí)是長(zhǎng)度超限。2.2 cbSize、uVersion 與那個(gè)共用體的歷史包袱cbSize是所有NOTIFYICONDATA故障里最隱蔽的一個(gè)。這個(gè)字段的用途是讓 shell 知道調(diào)用方用的是哪個(gè)版本的結(jié)構(gòu)體因?yàn)閺?Windows 2000 到現(xiàn)在這個(gè)結(jié)構(gòu)體加過(guò)好幾輪字段。寫(xiě)sizeof(NOTIFYICONDATA)在正常情況下永遠(yuǎn)是對(duì)的問(wèn)題出在兩種場(chǎng)景一是工程引用了很老的第三方 SDK 頭文件結(jié)構(gòu)體定義本身就缺字段sizeof算出來(lái)偏小二是用 C# 或其它語(yǔ)言手工定義StructLayout時(shí)字段漏了或者順序錯(cuò)了。第二種場(chǎng)景我踩過(guò)。C# 里為了不依賴 WinForms 的NotifyIcon有人會(huì)自己DllImport一個(gè)Shell_NotifyIcon然后手寫(xiě)一個(gè)NOTIFYICONDATA結(jié)構(gòu)體。少寫(xiě)一個(gè)guidItem或者把uTimeout的位置寫(xiě)錯(cuò)編譯一點(diǎn)問(wèn)題沒(méi)有運(yùn)行起來(lái)cbSize對(duì)不上NIM_ADD直接返回FALSE。這種情況在調(diào)試器里看一眼cbSize和預(yù)期值差多少基本就能定位。再說(shuō)uVersion。NOTIFYICONDATA里uTimeout和uVersion是共用同一塊內(nèi)存的union { UINT uTimeout; UINT uVersion; };也就是說(shuō)你不能在同一次調(diào)用里既設(shè)超時(shí)又設(shè)版本號(hào)。設(shè)置版本要用NIM_SETVERSION把uVersion填成NOTIFYICON_VERSION_4這個(gè)動(dòng)作會(huì)改變后續(xù)回調(diào)消息的編碼方式——lParam的低字是消息 ID高字是圖標(biāo) ID。很多人加了NIM_SETVERSION之后發(fā)現(xiàn)右鍵菜單不彈了就是因?yàn)榛卣{(diào)處理還在按老格式解析lParam。所以這條命令不是加了更好而是加了就得改回調(diào)。NOTIFYICON_VERSION_4還有另一個(gè)副作用uTimeout被徹底忽略氣泡停留時(shí)長(zhǎng)完全由系統(tǒng)的輔助功能設(shè)置決定。如果你有代碼依賴精確控制氣泡顯示 3 秒還是 10 秒那在 v4 下是做不到的。2.3 dwInfoFlags 里幾個(gè)會(huì)反向生效的標(biāo)志dwInfoFlags決定氣泡左側(cè)那個(gè)小圖標(biāo)的樣式常見(jiàn)取值是NIIF_NONE、NIIF_INFO、NIIF_WARNING、NIIF_ERROR、NIIF_USER。前四個(gè)都是系統(tǒng)內(nèi)置圖標(biāo)直接寫(xiě)就行NIIF_USER則需要額外配合hBalloonIcon字段。這里有個(gè)真實(shí)的坑NIIF_USER置位但hBalloonIcon留空時(shí)不同 Windows 版本的處理不一致有的版本回退到hIcon有的版本干脆畫(huà)一個(gè)默認(rèn)圖標(biāo)還有的版本會(huì)導(dǎo)致整個(gè)氣泡不顯示。我現(xiàn)在的做法是要么不用NIIF_USER用就老老實(shí)實(shí)把hBalloonIcon填上別指望系統(tǒng)幫你兜底。另一個(gè)有意思的標(biāo)志是NIIF_RESPECT_QUIET_TIMEWindows 7 引入的。置位之后如果系統(tǒng)處于安靜時(shí)間現(xiàn)在叫專注助手這條氣泡會(huì)被直接丟棄不是延遲顯示是丟棄。這個(gè)標(biāo)志的設(shè)計(jì)初衷是尊重用戶不想被打擾的意愿但如果你的程序發(fā)的是關(guān)鍵提醒置了這個(gè)位就等于主動(dòng)放棄了顯示機(jī)會(huì)。反過(guò)來(lái)如果你不置這個(gè)位系統(tǒng)在某些版本上仍然會(huì)按全局策略抑制橫幅——這一點(diǎn)各版本行為不完全一致所以不要用它來(lái)做能不能顯示的開(kāi)關(guān)。NIIF_NOSOUND相對(duì)簡(jiǎn)單加上就不響提示音。有個(gè)細(xì)節(jié)是它不影響氣泡本身的顯示只影響聲音所以別把它和靜音模式下氣泡不顯示混為一談。3. 代碼沒(méi)問(wèn)題但屏幕沒(méi)反應(yīng)系統(tǒng)層攔在哪3.1 通知總開(kāi)關(guān)、專注助手與安靜時(shí)間這是排查時(shí)最容易漏掉的一層因?yàn)樗辉谀愕拇a里而在用戶的機(jī)器上。Windows 10 之后系統(tǒng)設(shè)置里有一個(gè)通知和操作的總開(kāi)關(guān)關(guān)掉之后所有應(yīng)用的通知全部靜默下面還有按應(yīng)用細(xì)分的開(kāi)關(guān)以及專注助手的幾種模式關(guān)閉、僅優(yōu)先通知、僅鬧鐘。Shell_NotifyIcon發(fā)出的氣泡在 Windows 8 之后已經(jīng)被系統(tǒng)當(dāng)作通知來(lái)管理了所以它會(huì)完整地受這些開(kāi)關(guān)影響。表現(xiàn)是Shell_NotifyIcon返回TRUE氣泡不出現(xiàn)通知中心里也找不到。這種情況你改一萬(wàn)行代碼都沒(méi)用。排查手段是讓測(cè)試機(jī)恢復(fù)到默認(rèn)狀態(tài)通知總開(kāi)關(guān)打開(kāi)、專注助手關(guān)閉、當(dāng)前應(yīng)用在通知列表里處于允許狀態(tài)。還有一點(diǎn)如果程序以管理員權(quán)限運(yùn)行而系統(tǒng)設(shè)置里的通知是按應(yīng)用配置的某些版本下管理員進(jìn)程的通知配置和普通進(jìn)程不是同一份表現(xiàn)就是普通權(quán)限下能彈、提權(quán)后不彈。這個(gè)差異在不同系統(tǒng)版本上表現(xiàn)不一致我的做法是測(cè)試矩陣?yán)锕潭ò胀?quán)限和管理員權(quán)限兩行別只測(cè)一種。老系統(tǒng)上還有一個(gè)注冊(cè)表開(kāi)關(guān)HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced下的EnableBalloonTips值為 0 時(shí)禁用氣球提示。這個(gè)鍵在新系統(tǒng)上是否仍然生效取決于版本但在 Windows 7 時(shí)代它是標(biāo)準(zhǔn)的關(guān)閉方式排查老環(huán)境時(shí)值得看一眼。組策略里也有對(duì)應(yīng)的關(guān)閉通知?dú)馇蛱崾卷?xiàng)域環(huán)境下的機(jī)器可能被統(tǒng)一下發(fā)。3.2 會(huì)話與用戶身份Session 0 和 RunAs 的死角前面提過(guò)會(huì)話 0 的問(wèn)題這里展開(kāi)說(shuō)。Windows 的服務(wù)宿主機(jī)制決定了服務(wù)進(jìn)程運(yùn)行在會(huì)話 0那是一個(gè)沒(méi)有交互式桌面的獨(dú)立會(huì)話。任何在會(huì)話 0 里調(diào)用的 UI 相關(guān) API包括Shell_NotifyIcon、MessageBox、CreateWindow要么失敗要么創(chuàng)建一個(gè)用戶永遠(yuǎn)看不到的窗口。這個(gè)問(wèn)題在實(shí)際項(xiàng)目里通常表現(xiàn)為開(kāi)發(fā)機(jī)上好好的裝到客戶機(jī)上就沒(méi)通知。區(qū)別在于開(kāi)發(fā)機(jī)是雙擊 exe 運(yùn)行的客戶機(jī)上是通過(guò)服務(wù)或者計(jì)劃任務(wù)啟動(dòng)的。定位方法是在任務(wù)管理器里加一列會(huì)話 ID看進(jìn)程對(duì)應(yīng)的數(shù)字是不是和當(dāng)前登錄用戶一致。如果不一致那問(wèn)題不在代碼在于部署方式——要么改成用戶登錄后自啟動(dòng)要么用會(huì)話隔離機(jī)制把 UI 部分拆成一個(gè)運(yùn)行在用戶會(huì)話里的獨(dú)立進(jìn)程。還有一種情況是以另一個(gè)用戶身份運(yùn)行比如右鍵以其他用戶身份運(yùn)行或者用憑據(jù)管理器啟動(dòng)。這時(shí)圖標(biāo)會(huì)加到那個(gè)用戶的托盤里當(dāng)前登錄用戶看不到但那個(gè)用戶如果同時(shí)在線快速用戶切換在他自己的桌面里是能看到圖標(biāo)的?，F(xiàn)象就是我這邊沒(méi)圖標(biāo)但換個(gè)賬號(hào)登錄就有了很容易被誤判成偶發(fā) bug。3.3 Windows 8 之后氣球改頭換面成 Toast這條屬于知道就行不知道會(huì)繞遠(yuǎn)路的范疇。從 Windows 8 開(kāi)始Shell_NotifyIcon發(fā)出的氣球通知在視覺(jué)上已經(jīng)變成了 toast 樣式——從屏幕右下角滑入、停留幾秒、然后收進(jìn)通知中心。接口沒(méi)變樣式變了。這個(gè)變化帶來(lái)兩個(gè)實(shí)際影響。第一通知中心會(huì)成為這些氣泡的歸檔地用戶在通知中心里能看到歷史消息這意味著重復(fù)發(fā)同一條消息的行為和老系統(tǒng)不一樣了老系統(tǒng)上重復(fù)發(fā)會(huì)不斷彈新的新系統(tǒng)上可能出現(xiàn)合并或者覆蓋。第二某些系統(tǒng)版本上如果程序沒(méi)有設(shè)置AppUserModelID通知在系統(tǒng)里的歸屬會(huì)是一個(gè)默認(rèn)的宿主表現(xiàn)是通知列表里看不到你的應(yīng)用名用戶在設(shè)置里想允許你的通知都找不到對(duì)應(yīng)條目。設(shè)置AppUserModelID的 API 是SetCurrentProcessExplicitAppUserModelID在進(jìn)程啟動(dòng)早期調(diào)用。如果對(duì)通知的可靠性要求比較高其實(shí)可以考慮直接走 Toast 通知那套接口代價(jià)是需要注冊(cè)快捷方式、需要處理激活回調(diào)工程復(fù)雜度上一個(gè)臺(tái)階。托盤氣球勝在簡(jiǎn)單二十行代碼就能跑Toast 勝在可控能拿到點(diǎn)擊、能進(jìn)通知中心歸檔、能被用戶精細(xì)管理。選哪個(gè)取決于你的通知是順手提示一下還是業(yè)務(wù)流程的一環(huán)。4. 一條能自己走完的排查鏈路4.1 用三十行最小工程把業(yè)務(wù)代碼摘出去我處理這類問(wèn)題的固定第一步是新建一個(gè)空的 Win32 工程只保留一個(gè)隱藏主窗口、一個(gè)托盤圖標(biāo)、一個(gè)定時(shí)器定時(shí)器每三秒發(fā)一次氣泡。這個(gè)工程大概三十行寫(xiě)完不超過(guò)十分鐘。之所以要先做這一步是因?yàn)樵谡鎸?shí)項(xiàng)目里氣泡不顯示可能是業(yè)務(wù)邏輯、線程調(diào)度、窗口生命周期三者疊加出來(lái)的你直接在里面改參數(shù)改一次跑一次變量太多判斷不了哪個(gè)改動(dòng)起了作用。最小工程的骨架大致是這樣LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_CREATE: AddTrayIcon(hWnd); SetTimer(hWnd, TIMER_BALLOON, 3000, nullptr); return 0; case WM_TIMER: if (wParam TIMER_BALLOON) { ShowBalloon(hWnd, IDI_TRAY, L測(cè)試標(biāo)題, L這是一條測(cè)試氣泡, NIIF_INFO); } return 0; case WM_DESTROY: RemoveTrayIcon(hWnd); PostQuitMessage(0); return 0; } return DefWindowProc(hWnd, msg, wParam, lParam); }如果這個(gè)最小工程能彈氣泡說(shuō)明 API 用法和系統(tǒng)環(huán)境都沒(méi)問(wèn)題問(wèn)題在你的業(yè)務(wù)代碼里如果彈不出來(lái)說(shuō)明問(wèn)題在環(huán)境或者調(diào)用方式上接下來(lái)往系統(tǒng)層查。這一步能省掉一半的排查時(shí)間。4.2 返回值、窗口消息、監(jiān)視工具三處取證最小工程也不彈的時(shí)候取證要分三路走。第一路看返回值。Shell_NotifyIcon返回FALSE說(shuō)明 shell 明確拒絕了這時(shí)基本可以鎖定字段錯(cuò)誤cbSize不對(duì)、hWnd無(wú)效、uID沖突。返回TRUE但無(wú)顯示說(shuō)明接收端沒(méi)問(wèn)題問(wèn)題在展示端系統(tǒng)策略、會(huì)話、桌面可見(jiàn)性。這兩條分支的排查方向完全相反所以返回值必須看。第二路看窗口消息。如果要做氣泡點(diǎn)擊響應(yīng)uCallbackMessage指定的消息會(huì)在氣泡被點(diǎn)擊時(shí)發(fā)到你的窗口。用一個(gè)能抓窗口消息的工具掛在目標(biāo)窗口上觀察發(fā)氣泡前后有沒(méi)有WM_USER范圍內(nèi)的消息流動(dòng)。這一步主要是確認(rèn) shell 到底有沒(méi)有收到請(qǐng)求。第三路看系統(tǒng)狀態(tài)。通知設(shè)置、專注助手、會(huì)話 ID、是否提權(quán)這四項(xiàng)各花一分鐘確認(rèn)比讀一天文檔有用。我現(xiàn)在的習(xí)慣是在程序的關(guān)于頁(yè)面里放一個(gè)隱藏的診斷入口一鍵打印這幾項(xiàng)狀態(tài)客戶反饋問(wèn)題時(shí)讓他截個(gè)圖能省掉好幾輪來(lái)回?，F(xiàn)象優(yōu)先懷疑驗(yàn)證方式NIM_ADD返回 FALSEcbSize、hIcon為空、窗口句柄無(wú)效調(diào)試器里看cbSize與sizeof是否一致圖標(biāo)在氣泡無(wú)返回值 TRUEuFlags漏NIF_INFO斷點(diǎn)檢查發(fā)送時(shí)的uFlags值圖標(biāo)不在氣泡無(wú)會(huì)話 0、圖標(biāo)句柄被提前釋放任務(wù)管理器看會(huì)話 ID檢查DestroyIcon時(shí)機(jī)氣泡出但標(biāo)題空白字符集不匹配看sizeof(NOTIFYICONDATA)與工程字符集設(shè)置時(shí)好時(shí)壞消息循環(huán)被阻塞、定時(shí)器被搶占檢查主線程是否有長(zhǎng)耗時(shí)同步操作特定機(jī)器必現(xiàn)通知開(kāi)關(guān)、專注助手、組策略重置通知設(shè)置為默認(rèn)后復(fù)測(cè)4.3 把什么時(shí)候不彈記錄成日志這一點(diǎn)聽(tīng)起來(lái)平淡但它決定了后續(xù)排查是幾天還是幾小時(shí)。我在托盤模塊里加了一組固定的日志點(diǎn)NIM_ADD的結(jié)果、NIM_DELETE的結(jié)果、每次發(fā)氣泡前的uFlags和dwInfoFlags值、發(fā)氣泡的返回值、當(dāng)前進(jìn)程的會(huì)話 ID 和是否提權(quán)。這些信息加起來(lái)不到二十行代碼但客戶現(xiàn)場(chǎng)出問(wèn)題時(shí)看一眼日志就能把范圍縮小到一兩個(gè)方向。有個(gè)細(xì)節(jié)日志里不要把szInfo全文打進(jìn)去用戶數(shù)據(jù)可能很長(zhǎng)也可能包含不該落盤的內(nèi)容打個(gè)長(zhǎng)度和標(biāo)題就夠了。5. 托管封裝層WinForms 與 WPF 的等價(jià)坑5.1 NotifyIcon.ShowBalloonTip 的前置條件C# 的 WinForms 里NotifyIcon類把Shell_NotifyIcon包了一層接口看著簡(jiǎn)單坑一樣不少。ShowBalloonTip(int timeout)要能生效至少得滿足三個(gè)條件Visible為true、Icon不為null、圖標(biāo)已經(jīng)被系統(tǒng)接受。第一個(gè)條件是硬性的Visible false時(shí)調(diào)ShowBalloonTip不拋異常也不顯示最容易漏。第二個(gè)條件很多人以為只要給Icon賦值就行實(shí)際上如果你是從資源文件動(dòng)態(tài)加載圖標(biāo)流用完順手把StreamDispose掉了Icon對(duì)象的內(nèi)部句柄可能已經(jīng)失效表現(xiàn)就是托盤圖標(biāo)顯示成一塊空白氣泡也跟著不顯示。第三個(gè)條件在窗體生命周期早期容易出問(wèn)題。在Form_Load里立刻調(diào)ShowBalloonTip有些機(jī)器上不生效因?yàn)檫@時(shí)窗口句柄剛創(chuàng)建托盤圖標(biāo)還沒(méi)真正掛上去。穩(wěn)妥做法是Load之后用BeginInvoke推遲到消息隊(duì)列下一輪再調(diào)或者在Shown事件里調(diào)。timeout參數(shù)在 Vista 之后基本被忽略了實(shí)際時(shí)長(zhǎng)由系統(tǒng)的輔助功能設(shè)置決定。這一點(diǎn)和老系統(tǒng)不一樣如果產(chǎn)品文檔里寫(xiě)了氣泡顯示 5 秒最好改成約 5 秒實(shí)際由系統(tǒng)設(shè)置決定免得后面被當(dāng)成 bug 提。5.2 消息泵被堵住時(shí)氣泡會(huì)遲到Shell_NotifyIcon內(nèi)部是通過(guò)窗口消息和任務(wù)欄通信的這意味著它依賴調(diào)用線程的消息循環(huán)。如果主線程正在跑一個(gè)長(zhǎng)耗時(shí)同步任務(wù)比如讀一個(gè)大文件、等一個(gè)網(wǎng)絡(luò)請(qǐng)求、跑一段密集計(jì)算那么即使你在另一個(gè)線程里調(diào)ShowBalloonTip調(diào)用也可能被卡住直到主線程的消息泵重新轉(zhuǎn)起來(lái)?，F(xiàn)象很有迷惑性日志顯示已發(fā)送氣泡但用戶是在幾秒甚至幾十秒之后才看到或者干脆看不到因?yàn)橐呀?jīng)過(guò)了時(shí)效。這類問(wèn)題在后臺(tái)任務(wù)完成時(shí)彈通知的場(chǎng)景里特別常見(jiàn)因?yàn)楹笈_(tái)任務(wù)完成的時(shí)刻主線程往往正在刷新界面。處理辦法是有的把耗時(shí)任務(wù)放到后臺(tái)線程主線程只負(fù)責(zé) UI或者在不依賴NotifyIcon對(duì)象的場(chǎng)景下用一個(gè)獨(dú)立的隱藏窗口在自己的線程里跑消息循環(huán)來(lái)處理托盤消息。后者工程量大些但如果托盤邏輯要脫離主窗口獨(dú)立存活比如主窗口可以關(guān)閉但程序不退出這個(gè)結(jié)構(gòu)反而更清晰。WPF 這邊沒(méi)有內(nèi)置的托盤圖標(biāo)控件社區(qū)里常見(jiàn)的做法是引用 WinForms 的NotifyIcon或者用第三方庫(kù)。第三方庫(kù)如果自己實(shí)現(xiàn)了Shell_NotifyIcon的互操作那前面說(shuō)的cbSize、uFlags、字符集三件事依然適用換語(yǔ)言不換原理。選庫(kù)的時(shí)候可以看一眼它有沒(méi)有處理NOTIFYICON_VERSION_4沒(méi)處理的話右鍵菜單的坐標(biāo)計(jì)算在某些機(jī)器上會(huì)偏。6. 把這套東西做成不容易再出問(wèn)題的結(jié)構(gòu)6.1 用一個(gè)帶狀態(tài)位的發(fā)送函數(shù)收口在項(xiàng)目里我最后的做法是把托盤的添加刪除發(fā)氣泡三個(gè)動(dòng)作集中在一個(gè)小模塊里模塊內(nèi)部維護(hù)一個(gè)bool added狀態(tài)位任何一次NIM_ADD成功才置位NIM_DELETE后清零。發(fā)氣泡的入口函數(shù)第一件事就是檢查這個(gè)狀態(tài)位沒(méi)置位就先嘗試添加一次。這樣不管上層怎么調(diào)用都不會(huì)出現(xiàn)圖標(biāo)沒(méi)了還在發(fā)氣泡的靜默失敗。同時(shí)這個(gè)模塊對(duì)外只暴露一個(gè)ShowBalloon(title, text, level)函數(shù)level是個(gè)枚舉映射到NIIF_INFO、NIIF_WARNING、NIIF_ERROR。這樣上層不需要知道dwInfoFlags的存在后面如果要換實(shí)現(xiàn)比如換成 Toast 通知改動(dòng)面只在一個(gè)文件里。還有一個(gè)小設(shè)計(jì)發(fā)氣泡函數(shù)返回一個(gè)枚舉區(qū)分發(fā)送成功、發(fā)送失敗、系統(tǒng)策略可能抑制三種結(jié)果。第三種判斷不了那么準(zhǔn)可以根據(jù)會(huì)話 ID 和通知開(kāi)關(guān)做個(gè)粗略推斷。有這個(gè)返回值上層在做關(guān)鍵提醒時(shí)就能選擇走別的通道比如閃爍任務(wù)欄、改托盤圖標(biāo)顏色而不是把所有希望都押在氣泡上。6.2 退出時(shí)的清理和僵尸圖標(biāo)NIM_DELETE一定要在窗口銷毀之前調(diào)而且要用和NIM_ADD完全相同的hWnd和uID。我見(jiàn)過(guò)填錯(cuò)uID導(dǎo)致圖標(biāo)刪不掉的情況表現(xiàn)是程序退出后圖標(biāo)還掛在那兒鼠標(biāo)劃過(guò)才消失。這不僅僅是觀感問(wèn)題——?dú)埩舻膱D標(biāo)會(huì)占用那個(gè)uID下次啟動(dòng)如果復(fù)用同一個(gè) ID行為可能不可預(yù)期。另一個(gè)清理時(shí)機(jī)是WM_ENDSESSION系統(tǒng)關(guān)機(jī)或者注銷時(shí)程序不一定能走完正常的退出流程。在這個(gè)消息里補(bǔ)一次NIM_DELETE能減少殘留。還有崩潰場(chǎng)景進(jìn)程直接掛掉不會(huì)執(zhí)行任何清理代碼圖標(biāo)一定殘留這個(gè)沒(méi)辦法只能靠系統(tǒng)自己回收。如果程序支持多實(shí)例uID的分配要小心。兩個(gè)實(shí)例用同一個(gè)hWnd和uID是不可能的hWnd天然不同但如果用了自己生成的guidItem標(biāo)識(shí)兩個(gè)實(shí)例可能會(huì)互相覆蓋。多實(shí)例場(chǎng)景建議用單實(shí)例機(jī)制直接禁掉或者在guidItem里加入進(jìn)程相關(guān)的區(qū)分信息。6.3 版本差異下的降級(jí)策略不同 Windows 版本對(duì)氣泡的處理差異實(shí)際項(xiàng)目里沒(méi)必要逐一適配但有三條底線值得守住。第一條不要在NIM_ADD的時(shí)候一次性把NIF_INFO也帶上試圖順便彈個(gè)氣泡添加和修改分成兩次調(diào)用邏輯清晰出問(wèn)題也好定位。第二條NIM_SETVERSION只在確實(shí)需要 v4 的回調(diào)格式時(shí)才調(diào)調(diào)了就同步改回調(diào)解析邏輯兩者必須一起改。第三條uTimeout不要依賴需要多停留一會(huì)兒的需求用重復(fù)發(fā)送或者改成帶交互的通知來(lái)實(shí)現(xiàn)更好別指望這個(gè)字段。我在實(shí)際項(xiàng)目里的體會(huì)是托盤氣泡這個(gè)功能的問(wèn)題密度和代碼量完全不成比例——二十行代碼的功能可能需要幾百行的排查經(jīng)驗(yàn)來(lái)兜底。所以能把它封裝干凈就封裝干凈別讓業(yè)務(wù)邏輯直接碰NOTIFYICONDATA后面換人維護(hù)或者系統(tǒng)升級(jí)改一個(gè)文件就夠了。