Include code examples in separate file for Sandcastles

Question

I am trying to include code examples in the CHM file I am generating using Sandcastles. Here is what I have so far:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <example>
/// <code>
/// public int Test
/// {
/// private int test { get; set }
/// private int test2 { get; set; }
/// public int findE()
/// {
/// if(test == test2){
/// return Console.WriteLine("Variables are Equal")
/// }
/// else{
/// return Console.WriteLine("Variables are not equal")
/// }
/// }
/// }
/// </code>
/// </example>

This is very messy and I would rather not have this code in my .cs file. Is there a way to put this example code in a separate .cs file and in some way reference this in the comment? So instead I would have something like this:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <reference src="mycode.cs">
/// </example>

Answer 1

Sure. Say you create an external code file, Example.cs. In that file you place your example, surrounded by a named region .

#region example1
Console.WriteLine("Hello, World!");
#endregion

In the XML comment for the element you're creating the example for, you specify the source of the external code example:

/// <summary>blah blah my class</summary>
/// <example><code source="Example.cs" region="example1" lang="C#" 
/// title="Some Title to Display" /></example>
public class Hurr
{
 // ...

Specifying the language isn't necessary for C# as that is the default, and if you don't specify the region, it will include all the code in your example file.

Also note that the source filepath is relative to your SHFB project file, not necessarily the Visual Studio project file. If you configure the Code Block Component (in SHFB -> Project Properties -> Components) you can specify a different base path.