【Avalonia】Windowsのトレイアイコンが透明になる不具合の原因と解決策（v12.1.3で修正）

概要

Avaloniaでシステムトレイ（タスクトレイ）常駐型のWindowsデスクトップアプリケーション「ClickCapture」を開発していた際、「タスクバーの『その他のシステムトレイアイコン』（隠れているインジケーター）一覧で、アプリアイコンが透明化/プレースホルダー化してしまう」という描画不具合に直面しました。

約3ヶ月ほど原因の調査に試行錯誤しましたが、Avalonia 12.1.3 でフレームワーク側のライフサイクルバグが修正されたことで無事に解決しました。

本記事では、発生した現象の概要、試した切り分けプロセス、および問題の根本原因（PR #22118）についてまとめます。

---

発生した現象

• 環境: Windows 11, Avalonia UI（12.1.2以前）
• 症状:
  • 通常のタスクバー上ではトレイアイコンが正しく描画される。
  • Windows設定の 個人用設定 > タスク バー > その他のシステムトレイアイコン（オーバーフロー領域）を開くと、アイコンのグラフィックが消えて透明（または無地の領域）になる。

---

試したアプローチと切り分け

当初はアプリ側の実装ミスやOS側の仕様を疑い、以下の検証を行いました。

1. よくある対策（効果なし）

• アイコンキャッシュの削除: レジストリ（IconStreams 等）の削除および explorer.exe の再起動。
• ICOファイルのフォーマット変更: 16x16, 32x32, 48x48 などのマルチサイズアイコンや色深度の見直し。
• UIスレッド/生成タイマー調整: Task.Delay によるアタッチタイミングの遅延処理。

いずれも効果がなく、現象は再現し続けました。

2. Win32APIによる自前実装（切り分け成功）

フレームワークの抽象化層をスキップし、Shell_NotifyIcon などの Win32 Native API を直接呼び出す P/Invoke ヘルパーコードを実装して検証しました。

// Shell_NotifyIcon を直接呼び出すネイティブ登録の検証
var nid = new NativeMethods.NOTIFYICONDATAW
{
    cbSize = (uint)Marshal.SizeOf<NativeMethods.NOTIFYICONDATAW>(),
    hWnd = hwnd,
    uID = 1,
    uFlags = NativeMethods.NIF_MESSAGE | NativeMethods.NIF_ICON | NativeMethods.NIF_TIP,
    uCallbackMessage = NativeMethods.WM_TRAYICON,
    hIcon = hIcon,
    szTip = tooltip
};
NativeMethods.Shell_NotifyIcon(NativeMethods.NIM_ADD, ref nid);

Win32APIを直接叩いた場合は、オーバーフロー領域でも問題なくアイコンが表示されることが確認できました。この結果から、「問題はアプリの画像リソースやOSのキャッシュではなく、Avalonia側の TrayIcon ライフサイクル管理にある」 と特定できました。

---

根本原因：Avaloniaの TrayIcon アタッチライフサイクル

Avalonia 12.1.3 のリリースノートにて、まさに本不具合を修正するプルリクエストがマージされました。

• 修正PR: PR #22118 - Controls – Fix TrayIcon attachment lifecycle

原因のメカニズム

1. 修正前: TrayIcon のコンストラクタが呼び出された時点で、直ちにOSへネイティブ登録（アタッチ）が行われていた。
2. 問題点: アプリケーションの初期化途中（プロパティやリソースの準備が完了していない状態）でWindows側にアタッチされていたため、OS側のオーバーフロー表示用キャッシュに不完全なデータが登録されてしまっていた。
3. 修正後: コンストラクタでの即時アタッチを廃止し、TrayIcons コレクションへの追加やプロパティの完全な初期化に同期してネイティブハンドルの生成・登録を行うライフサイクルへ変更された。

---

解決策

csproj の Avalonia パッケージバージョンを 12.1.3 以降 に更新します。

<ItemGroup>
  <!-- 12.1.3 以降にアップデート -->
  <PackageReference Include="Avalonia" Version="12.1.3" />
</ItemGroup>

バージョンを更新して再ビルドした結果、特別なキャッシュ破棄などを伴わずに「その他のシステムトレイアイコン」画面でも正常にアイコンが描画されるようになりました。

---

まとめ

Avaloniaでトレイアイコンが特定の領域で透明化・描画不良を起こす場合、画像フォーマットやWindowsのキャッシュを疑う前にAvaloniaのバージョンを確認することをお勧めします。

12.1.2 以前を使用している場合は、12.1.3 以降へアップデートすることで解決できます。

---

※常駐アプリ開発の検証例として使用したクリック自動撮影ツール「ClickCapture」も公開しています。Avaloniaでの常駐ツール実装に興味のある方はご覧ください。

---