ASP.NET 自訂控制項 ToolboxBitmap 屬性完整設定指南

開發 ASP.NET 伺服器控制項時，預設工具箱圖示為統一的藍色齒輪，缺乏辨識度。透過 ToolboxBitmapAttribute 可指定自訂 16×16 像素、256 色 BMP 圖示，但命名空間與資源命名規則常導致圖示無法顯示。本文詳細說明兩種常見情境的正確設定方式。

前置準備

1. 準備 16×16 px、256 色 .bmp 圖檔
2. 將圖檔加入專案，屬性視窗將 建置動作 設為 嵌入的資源

情境一：控制項無自訂命名空間

• 組件名稱：MyControls.dll
• 控制項類別：MyBox（無 namespace）
• 圖示檔名：MyBox.bmp
• 資源完整名稱：MyControls.MyBox.bmp（預設：專案預設命名空間 + 檔名）

[ToolboxBitmap(typeof(MyBox), "MyBox.bmp")]
public class MyBox : WebControl { ... }

此情況下，ToolboxBitmap 甚至可省略，預設會依類別名稱尋找同名 .bmp。

情境二：控制項有自訂命名空間

• 組件名稱：MyControls.dll
• 控制項類別：MyBox
• 命名空間：Boxes
• 圖示檔名：MyBox.bmp
• 資源完整名稱：MyControls.Boxes.MyBox.bmp

namespace Boxes {
    [ToolboxBitmap(typeof(MyBox), "MyBox.bmp")]
    public class MyBox : WebControl { ... }
}

關鍵點：若保持原檔名 MyBox.bmp，資源名稱會是 MyControls.MyBox.bmp，找不到 Boxes.MyBox.bmp 導致圖示失效。解決方法：將圖檔重新命名為 Boxes.MyBox.bmp（含命名空間前綴），嵌入資源後完整名稱即為 MyControls.Boxes.MyBox.bmp，與屬性指定的 "MyBox.bmp" 搭配運作。

驗證資源名稱技巧

// 偵錯時列印所有嵌入資源名稱
var asm = Assembly.GetExecutingAssembly();
foreach (var name in asm.GetManifestResourceNames()) {
    System.Diagnostics.Debug.WriteLine(name);
}

常見錯誤彙整