Providing complete examples

Apr 9, 2009 at 11:57 AM
I am working on documentation for a class library. I'd like to write how-to-s that include sample source. I can do that with code blocks, but I'd like that code to come from real samples that are compiled and linked, therefore avoiding including samples that don't work and avoiding a lot of typing.

What's the best way to achieve that?

Ideally I'd like something like <codeEntityReference full="true">M:Namespace.Class.Function</codeEntityReference>.
Apr 9, 2009 at 7:18 PM
The custom Code Block Component distributed with the Sandcastle Help File Builder and also available in a standalone download for use with other build tools or scripts can be used to do that.  You'll find both at  It works in both XML comments and MAML topics.  You can specify a source attribute on a <code> tag to import a source file and an optional region attribute to limit the imported code to a specific region within the file.  The component is paired with the included Post Transform component.  The code block component handles the import, code colorization, etc. and the post transform component handles inserting the code into the HTML topic along with the supporting stylesheet and script file.  The included help file contains usage notes but if you have any questions you can ask them over in the SHFB project's discussion forum.

Apr 10, 2009 at 8:33 PM
That worked, thank you.