How to add platform icons to generated help

Nov 13, 2011 at 5:28 AM

I am building help file for my library using Sandcastle Help File Builder. The library has three versions (.NET, Silverlight and Windows Phone 7) built from the same code base.

I would like to add platform icons next to method names on relevant help file pages. Something like on screenshot below. How can I add such information to my help file?

Platform icons next to method names

Nov 14, 2011 at 5:12 AM

Hello Bobrovsky,

The platform information handler is the PlatformsComponent, which is included in the current Sandcastle.
Searching through the sample configuration files, I have also found that component must be configured as

<component type="Microsoft.Ddue.Tools.PlatformsComponent" assembly="BuildComponents.dll">
  <!-- The order of filter files in this config determines the order of platforms in the output. -->
  <filter files=".\SupportFiles\Platforms\WinVista.xml"/>
  <filter files=".\SupportFiles\Platforms\WinXP.xml"/>
  <filter files=".\SupportFiles\Platforms\SmartPhone.xml"/>
  <filter files=".\SupportFiles\Platforms\PocketPC.xml"/>
  <filter files=".\SupportFiles\Platforms\Xbox360.xml"/>

Unfortunately, that is all that is available for the platform information.
Now, I think there are two things involved here; version information and platform information.
Information on the version information is released (even though not completely) and the tool, VersionBuilder.exe
is also available. But the platform information and tool required to build the filter files listed above are not made
available.  Even the format of the filter files listed above are not known - at least I have not seen it yet.

Initially, I did work on the version information for my build tools and decided to forget about the platform information.
But, since you asked, I have managed to construct the format of the filter files (will still need to test them to know if I got
it right). 

Stay tuned, I hope to get it working soon, but you will have to do the extra work to get it working in SHFB, if successful.

Best regards,

Nov 14, 2011 at 1:57 PM

Hello Paul,

Thank you for your answer. It sheds some light on the problem. At least now I know why I wasn't able to add platform icons to my help file.

It's not completely clear for me what should be done in SHFB to use platform information and tool once it will be released but I assume you will tell this later.

Anyway, I am very interested to get all this done, so I'll wait for more information from you.

Thank you again.

Jan 9, 2012 at 2:30 AM
Edited Jan 10, 2012 at 4:21 PM

Hello Bobrovsky,

Happy New Year! This feature is a bit confusing to implement and could be the reason why
the Sandcastle Team left it out in the consumer release of the Sandcastle.

The good news is after struggling with this for a long time I have managed to get it to work!
You can see some screenshot of samples built with my tools on Google+ photos (Picasa):

Platform Information

An even better news is that it is almost completely implemented by the current transforms, so you will
not have to modify the styles to get it to work. The bad news is that version identifiers (ID) for Silverlight 5,
.NET 4.5, and Windows Phone 7.1 (is it 7.5? I'm Android user!) are not defined, but you can guess the IDs from the current values in the content file. 
Also, the platform + version IDs + Icon for the new Portable Class Library are not defined. This will involve trying to extract that information (somehow) from the online metadata of the MSDN help files.

The actual bad news is that it will take you some work to get it to work with SHFB. You can start by learning
how the plugin system there works and how the current version information plugin is implemented, since you
are going to re-implement the whole version information plugin.

I will guide you on how the version/platform information works, and provide you the code, which you can modify
to generated the platform file I talked about in the earlier post, but will not be able to walk you through writing the
plugin. How you will generate the platform file depends on project structure, but will give you full knowledge of the
format, at least what I got so far. 

Best regards,

Jan 9, 2012 at 7:31 PM

If you'd care to share the necessary information with me, I can modify the plug-in to include the platform data.  You can either e-mail the info to me or create a work item in the SHFB project and attach the info there.  Thanks.



Jan 10, 2012 at 2:41 PM

Hello Paul,

Thank you for the good news and Happy New Year!

I am still interested in getting platform icons next to method/property names in my help file, so I am all ears. There is one thing, though: I have no knowledge about how plug-ins for SHFB should be implemented.

Could you please briefly describe how the version/platform information works, so I can roughly estimate amount of time required for the plug-in development?

Jan 10, 2012 at 4:39 PM

Hello Bobrovsky,

The version/platform information is not difficult to understand, but requires you
understand the documentation building process/steps.

The following are the articles by the Sandcastle Team to explain the version information

Part 1, which is the main tutorial.

Part 2, provides illustrative example.

Please read them and let me know if you understand these articles (mainly the part 1), 
we will see what to do.

Best regards,

Jan 18, 2012 at 4:22 PM

Hello Paul,

Thank you for the links. 

I kind of understand the tutorial but not sure that understand it enough to build a plug-in for SHFB. 

Jan 18, 2012 at 7:32 PM

If Paul shares the necessary info, I'll update the existing version builder plug-in for SHFB to support the platform information.



Jan 19, 2012 at 3:31 AM

Hello Bobrovsky,

I realized you really need this and will find the best way to document the feature, so that anyone can implement it.

Best regards,


Jan 19, 2012 at 5:57 PM

Hello Eric,


Thank you.

I guess you are the one who knows most about SHFB and its plugins. 

Jan 19, 2012 at 6:04 PM

Hello Paul,


Thank you for the willingness to help me and other users of Sandcastle/SHFB.

I asked about all this on some time ago. And although I didn't get any answers there, I think there are some other developers interested in adding platform icons to their help files.

Jan 21, 2012 at 12:05 PM
Edited Feb 6, 2012 at 4:25 AM

Hello Bobrovsky,

I have started 3-part article to explain the version information.
Part 1: Introduction to Version/Platform Information  (Available Now)
Part 2: Version Information Implementation              (Available Now)
Part 3: Platform Information Implementationn           (Available Now)

Part 2 will discussion the Sandcastle official articles and add the missing bits.

Part 3 will provide the platform information and the tool codes, this is where the icon stuff is discussed.

The blog is available at the Sandcastle Assist blog site

Best regards,

Feb 6, 2012 at 4:32 AM

Hello All,

I have finally completed the articles on the version and platform information.
Also included are test projects to demonstrate these Sandcastle features and the codes
to generate the platform file.

If you have any question or issue, post it here or as comment on the articles.

NOTE: These are not well edited yet, so prepare to put up with some poor grammar :(

Have a nice week.

Best regards,