C# WinForm自定义控件ToolboxBitmap嵌入资源图标不显示问题

ToolboxBitmap特性引用嵌入资源图标失效，基本都是资源匹配规则理解错、VS缓存、图标格式不符合要求这三类原因，按下面步骤逐一排查即可：

1. 先确认图标本身符合VS工具箱要求 #

• 尺寸必须是16*16像素
• 不要带Alpha半透明通道，VS2022部分更新版本对带透明通道的PNG图标识别有bug，会直接回退显示默认控件图标，建议先用24位无透明的BMP格式测试，确认逻辑通了再调整PNG透明效果。

2. 用类型重载的特性写法避免资源路径解析错误 #

绝大多数人写[ToolboxBitmap("DemoIconInToolBox.icon.png")]不生效，是因为单字符串参数的重载默认按当前应用程序域的基址解析资源，不会自动匹配程序集清单里的资源路径，最稳妥的写法是用传入控件类型的重载，让CLR自动从控件所在程序集加载对应资源：

// 把YourCustomControl替换成你自己的自定义控件类名
// 如果icon.png直接放在项目根目录，和控件类同命名空间，第二个参数直接传文件名即可
[ToolboxBitmap(typeof(YourCustomControl), "icon.png")]

如果你的图标放在项目的子文件夹下，比如放在Resources文件夹里，第二个参数要传入带文件夹层级的相对路径："Resources.icon.png"，命名空间层级和文件夹层级要对应。

3. 确认资源生成操作配置正确 #

右键项目中的icon.png文件，打开属性面板，确认「生成操作」选中的是嵌入的资源，不要选.resx资源专用的「Resource」选项，后者不会把文件作为独立清单资源嵌入，ToolboxBitmap特性读不到。
你可以用下面这段测试代码打印程序集内所有嵌入资源的完整名称，确认资源确实被正确嵌入：

var assembly = typeof(YourCustomControl).Assembly;
foreach (var resName in assembly.GetManifestResourceNames())
{
    // 输出到VS调试输出窗口
    System.Diagnostics.Debug.WriteLine(resName);
}

如果输出的列表里找不到你的icon.png对应的资源名，说明生成操作配置错误，重新设置后重新生成项目即可。

4. 清除VS工具箱缓存 #

配置完全正确但还是显示默认图标，基本是VS本地缓存了旧的工具箱数据，按下面步骤清缓存：

• 关闭所有正在运行的Visual Studio进程
• 打开文件资源管理器，在地址栏输入%LOCALAPPDATA%\Microsoft\VisualStudio\回车
• 找到对应VS2022版本的文件夹（命名格式为17.0_xxxxxx，后缀是随机字符串），进入文件夹后删除所有后缀为.tbd的文件
• 重新打开VS，重新生成控件项目，重新把控件添加到工具箱，就能看到自定义图标了。

避坑提示：如果你的控件项目强签名了，记得重新添加到工具箱的时候要引用最新生成的DLL，不要引用之前GAC里注册的旧版本，旧版本里没有嵌入图标资源也会显示默认图标。

内容的提问来源于stack exchange，提问作者Mads Aggerholm