C# 自訂控制項嵌入專屬圖標：ToolboxBitmapAttribute 完整指南

一、為什麼要嵌入自訂圖標？

在 Visual Studio 工具箱中，自訂控制項預設顯示通用齒輪圖標，難以辨識。嵌入專屬圖標（16×16 .bmp/.ico）能：

• 提升工具箱辨識度，加速開發效率。
• 強化元件專業感，便於團隊協作與第三方發布。
• 圖標隨組件封裝部署，避免外部檔案遺失。

二、完整操作步驟

步驟 1：準備圖標資源

• 格式：.bmp (推薦) 或 .ico
• 尺寸：16 × 16 像素 (工具箱標準大小)
• 命名：建議與控制項類別名一致（如 `MyCustomControl.bmp`）

步驟 2：加入專案並設為嵌入資源

1. 在專案上右鍵 → **Add** → **Existing Item** 選取圖標檔。
2. 選中圖標檔，在 **Properties** 視窗中將 **Build Action** 設為 **Embedded Resource**。

步驟 3：在控制項類別套用 ToolboxBitmapAttribute

using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;

namespace MyControls
{
    // 關鍵：指定圖標資源名稱 (預設命名空間.檔案名)
    [ToolboxBitmap(typeof(MyCustomControl), "MyCustomControl.bmp")]
    public partial class MyCustomControl : UserControl
    {
        public MyCustomControl()
        {
            InitializeComponent();
        }
        // 控制項邏輯...
    }
}

三、資源名稱解析規則

`ToolboxBitmapAttribute` 以 **預設命名空間 + 檔案名** 尋找嵌入資源。常見情況：

驗證技巧：編譯後用 ILSpy/reflector 查看 `.resources` 確認實際資源名稱。

四、進階：針對不同尺寸提供圖標 (HiDPI 支援)

.NET 4.6.2+ 支援 `ToolboxBitmapAttribute` 多載，可分別指定 16×16 與 32×32 圖標：

[ToolboxBitmap(typeof(MyCustomControl), "MyCustomControl_16.bmp")]
[ToolboxBitmap(typeof(MyCustomControl), "MyCustomControl_32.bmp", true)] // true = 32x32
public partial class MyCustomControl : UserControl { }

或實作 `IToolboxUser` 介面動態提供（較複雜，少用）。

五、WPF 自訂控制項的圖標嵌入

WPF 控制項同樣適用，但建議使用 **.png** 並透過 `ToolboxBitmapAttribute` 指定：

[ToolboxBitmap(typeof(MyWpfControl), "MyWpfControl.png")]
public class MyWpfControl : UserControl { }

注意：WPF 設計器在 VS 2019+ 對 PNG 支援良好，舊版建議用 BMP。

六、常見問題排查

七、最佳實踐總結

1. **統一命名**：圖標檔名 = 控制項類別名 + `.bmp`。
2. **集中管理**：建立 `Resources\ToolboxIcons` 目錄存放所有圖標。
3. **建置腳本驗證**：CI 中加入步驟檢查嵌入資源是否存在。
4. **版本控管**：圖標檔納入 Git，隨代碼同步演進。

只需三步驟（加檔案、設嵌入、加 Attribute），即可讓自訂控制項在工具箱中擁有專屬形象，是元件開發的專業標配。