Walkthrough: Creating Managed Satellite DLLs

Satellite DLLs are useful for storing resource files, such as icons, bitmaps, and resource strings, in a centralized location for use in add-ins and other automation projects. Satellite DLLs can be reused by other projects or add-ins. Furthermore, separating the strings and other resources from your add-in makes it easier to make centralized changes or localize the resources into different languages.

Visual Studio .NET 2002 and Visual Studio .NET 2003 used registry entries for SatelliteDllPath and SatelliteDllName. However, in Visual Studio 2005, registry entries are superseded by entries in the .Addin registration file. When you need a resource in your project, you load the add-in and Visual Studio queries it for the satellite DLL, just like other managed components. Consequently, hard coding a resource path is not necessary. Also, instead of using the #id method to specify a resource ID, you use @<resource name> (where "<resource name> is the name of your resource, such as @Icon1 or @String1), The @ symbol indicates to Visual Studio that it should look in the satellite DLL for the resource.

Create Managed Satellite DLLs

The following procedure demonstrates how to create a satellite DLL containing icon and string resources and how to alter an add-in to access those resources. It uses an add-in that has an About Box, which requires icon and string resources. Normally, if you create an add-in with an About Box, a default icon and text are provided. The procedure below shows how to replace that with an icon and text of your choosing.

To create a managed satellite DLL

1. From the File menu, point to New, and then click Project.

   The New Project dialog box opens.

2. Expand Other Project Types and then select Extensibility Projects.

3. In the Templates pane select Visual Studio Add-in.

4. Follow the directions of the Visual Studio Add-in Wizard. On the Choosing 'Help About' Information page, check the Yes, I would like my Add-in to offer 'About' box information check box. Accept the remaining default choices.

5. In Solution Explorer, select your add-in project and, on the Project menu, click Show All Files.

6. On the Project menu, click Add Reference.

7. On the .NET tab, click System.Drawing, and then click OK.

8. Right-click the add-in project in Solution Explorer.

9. Point to Add and click New Item.

10. Select Resources File in the Templates list and click the Add button. Leave its default name (Resources1.resx).

    This starts the Visual Studio Resource Editor.

    By default, this creates a resource file named Resource1.resx.

11. In Resource1.resx, select Icons from the Strings dropdown at the top (the left-most button at the top).

12. In the Add Resource dropdown, click Add New Icon. For now, leave its default name (Icon1.bmp) and click Add.

    Alternatively, you can select an existing bitmap image for the icon as long as it is 16 x 16 pixels and either 16 Color or True Color. Custom icons for add-ins must be 16 x 16 pixels and be either 16-color or True Color.

13. After the icon opens in the Icon Editor, use the tools to alter it. When you are done, close the Icon Editor and save your changes.

14. Select Add New String from the Add Resource dropdown.

15. Click the first box in the Name column.

    This creates a new default string resource named String1.

16. Type Line one in the Value box.

    This is the value for the first string resource.

17. Create two more string resources, naming them "Line two" and "Line three".

18. Close the Resource Editor and save the changes.

19. In Solution Explorer, right-click Resource1.resx and select Properties.

20. In the Properties window, change Build Action from Embedded Resource to None.

    This prevents the resource from being built into the add-in assembly.

21. Build the project.

22. Create the satellite resource DLL. This is done in a two step process by using ResGen and then AL (Assembly Linker) to build the satellite DLL.

    1. Click the Windows Start button, point to All Programs, point to Microsoft Visual Studio 2005, point to Visual Studio Tools, and click Microsoft Visual Studio 2005 Command Prompt.

       This sets certain environment variables so that you can more easily reference Visual Studio tools.

    2. At the command prompt, go to the folder containing the .resx file and type Resgen Resource1.resx.

       Resgen is a utility that compiles the specified .resx file into a .resources file. For more information, see Resource File Generator (Resgen.exe).

    3. Again, at the command prompt, type the following: Al.exe /embed:Resource1.resources /culture:en-US /out:<Add-In Name>.resources.dll.

       Replace <Add-In Name> with the name of your add-in. For example, if your add-in project is named MyAddin, then the /out: switch would be /out:MyAddin.resources.dll. The /out: name must match the name of your project, or else the resource DLL will not be found.

       Al.exe (Assembly Linker) converts the specified .resources file into a DLL that you can reference in your add-in. (You can change the /culture switch to a language other than English.) For more information, see Assembly Linker (Al.exe).

23. Using Windows Explorer, browse to the add-in's DLL directory and create a folder named en-US (for English US, because you typed en-US as the culture value in Al).

24. Copy the <Add-In Name>.resources.dll file to the new en-US folder.

25. Using Windows Explorer, browse to the Addins directory. Usually <drive>:\Documents and Settings\<user name>\My Documents\Visual Studio 2005\Addins.

26. Modify the Visual Studio add-in definition file by doing the following:

    1. Right-click the add-in definition file for your add-in, and select Open With from the shortcut menu. Select Note Pad from the list of programs.

    2. Inside the <Addin></Addin> tags, make the following modifications:

       <Addin>
           <FriendlyName>@String1</FriendlyName>
           <Description>@String2</Description>
           <AboutBoxDetails>@String3</AboutBoxDetails>
           <AboutIconData>@Icon1</AboutIconData>
           <Assembly><installation root>\my documents\visual studio 2005\Projects\MyAddin1\MyAddin1\bin\MyAddin1.dll</Assembly>
           <FullClassName>MyAddin1.Connect</FullClassName>
           <LoadBehavior>0</LoadBehavior>
           <CommandPreload>0</CommandPreload>
           <CommandLineSafe>0</CommandLineSafe>
       </Addin>
       

       Replace the <installation root> inside the <Assembly></Assembly> tags with the file path on your computer.

       The Friendlyname entry renames your add-in to Line1, which is what you entered for String1 in the Resource1.resx file. The Description in the Help About box now contains "Line2", and the AboutIconData entry matches the icon in the Help About box to the icon you created in step seven (7).

27. Rebuild the project and select the add-in in the Add-in Manager.

28. On the Help menu click the About Microsoft Visual Studio command and select Line1 (the name of your add-in) in the list.

    You see your new custom icon and the three strings you created in the About Box.

See Also

Tasks

How to: Access Resources in Satellite DLLs

Concepts

Add-in Registration