Включить примеры кода в отдельный файл для Sandcastles

Question

Я пытаюсь включить примеры кода в CHM-файл, который я генерирую с помощью Sandcastles. Вот то, что я до сих пор:

/// <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> 

Это очень грязно, и я не хотел бы иметь этот код в моем файле .cs. Есть ли способ поместить этот примерный код в отдельный файл .cs и каким-то образом ссылаться на него в комментарии? Поэтому вместо этого у меня было бы что-то вроде этого:

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

Answer 1

Несомненно. Скажем, вы создаете внешний файл кода, Example.cs. В этом файле вы разместите свой пример, окруженный именем region.

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

В XML-комментарии для элемента, который вы создаете пример для, необходимо указать источник внешнего кода, например:

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

Указание языка не является необходимым для C#, что и по умолчанию, и если вы не укажете регион, он будет содержать весь код в вашем примере файла.

Также обратите внимание, что путь к исходному файлу относится к вашему файлу проекта SHFB, а не обязательно к файлу проекта Visual Studio. Если вы сконфигурируете Компонент блока кода (в SHFB -> Свойства проекта -> Компоненты), вы можете указать другой базовый путь.