Huizhong Long's WebLog

Displaying custom bitmap for VS add-in command button from satellite DLL

Add-ins can get resources such as strings, icons, and bitmaps from satellite DLLs which separates resources from your add-in. The first time I tried to get add-in resources from its satellite DLL, I easily find out how to do it for resources like strings and icons. But for bitmaps, it took me really a long time to figure out (for both native & managed add-ins). There indeed are some tricky steps that are hard to find out, so I thought it would be really good to blog it.

In previous verions of VS (2002 & 2003), add-ins used reg key values "SatelliteDllName" and "SatelliteDllPath" to store info for satellite DLLs. Now with Visual Studio 2005, you don't need to bother with registry for managed add-ins (although you still need it for native add-ins) any more. For resources like strings and icons, it is quite straightforward. To briefly state here, you simply prepend the resource name with the @ character in the .Addin XML file, in this way the add-in will look for the resource from its satellite DLL, e.g. <FriendlyName>@String1</FriendlyName>. "String1" is the resource name in the satellite DLL. One thing I want to point out is, for add-in Help/About box icon, you need to use tag <AboutIconLocation> instead of <AboutIconData>, like <AboutIconLocation>@Icon1</AboutIconLocation>, which may be confusing.

For resources like bitmaps, the way you get it from satellite DLLs is quite different and tricky. From my experience, It seems like if you miss one little step, you won't get it work and it is hard to figure out what's going wrong. What's more, the way you do it for native add-ins and managed add-ins is different. So I am going to list the steps in detail here for both native & managed add-ins respectively:

    1. Create a C++ Win32 DLL
    2. Add a Resource File (.rc)
    3. In Resource View, add a bitmap (16 x 16), give it a numeric ID
    4. Build the DLL
    5. Create a subfolder "1033" (for English locale) in the native add-in DLL directory
    6. Copy the satellite DLL to "1033" directory

To get the bitmap show up with the command, make sure
    1. The bitmap must be 16 x 16 (True Color)
    2. Update AddNamedCommand2 in Connect.cpp with 'MSOButton' set to VARIANT_FALSE, and 'Bitmap' set to the bitmap ID
    3. Open AddIn.rgs and add two reg key values "SatelliteDllName" and "SatelliteDllPath" (see the example below)
    4. Rebuild the add-in to get the updated info registered

(NOTE: One thing you may miss here in 3. is: for "SatelliteDllPath" do not put the locale ID although it is part of the full path, it will be automatically appended at runtime)

Here is an example:

HKCU
{
 NoRemove 'SOFTWARE'
 {
  NoRemove 'Microsoft'
  {
   NoRemove 'VisualStudio'
   {
    NoRemove '8.0'
    {
     NoRemove 'AddIns'
     {
      ForceRemove 'NativeAddinCustBitmap.Connect'
      {
       val LoadBehavior = d 0
       val CommandLineSafe = d 0
       val CommandPreload = d 1
       val FriendlyName = s 'NativeAddinCustBitmap'
       val Description = s 'NativeAddinCustBitmap Description'
       val SatelliteDllName = s 'NativeAddinCustBitmapUI.dll'
       val SatelliteDllPath = s 'E:\CustomBitmap\NativeAddinCustBitmap\NativeAddinCustBitmap\Debug'
      }
     }
    }
   }
  }
 }
}

Creating a managed satellite DLL with a custom bitmap and getting it from a managed add-in:

    1. Add a Resources file to the managed add-in project, say "Resource1.resx" (set the Build Action to None)
    2. Add your bitmap (16 x 16) to the resource, give the bitmap a numeric ID
    3. Run "resgen Resource1.resx" to create "Resource1.resources"
    4. Run "al.exe /embed:Resource1.resources /culture:en-US /out:YourAddinName.resources.dll
    (use System.Globalization.CultureInfo.InstalledUICulture to get the correct culture, here I use 'en-US' as an example.)
    5. Create a subfolder named 'en-US' or the correct culture name in the add-in DLL directory
    6. Copy YourAddinName.resources.dll to the subfolder created in step 5.
       (One handy thing is that you don't even need to put satelliteDll info in the .AddIn XML file.)

To get the bitmap show up with the command, make sure:
    1. The bitmap must be 16 x 16 (True Color or 16 Color)
    2. The bitmap must have a name that is actually decimal number. The ResX designer in VS doesn't allow numeric IDs for resources. You have to edit the resx directly and ignore the warnings.
    3. Update AddNamedCommand2 with 'MSOButton' param set to false, and the 'bitmap' param set to the bitmap ID.

Hope I have made it clear.