Как правильно ссылаться на встроенные ресурсы в комментариях .net xmldoc?

Question

У меня есть проект C #, который использует xml comments . Я делаю из них файлы chm с помощью Sandcastle через Sandcastle Help File Builder . Одна из функций-членов в этом проекте использует встроенный ресурс . Я хочу сослаться на это в файле справки. Кажется, что sandcastle не поддерживает это, но анализирует файлы документации xml. Я говорю это из-за следующего примера

/// <summary>
/// Displays the resource text.
/// </summary>
/// <remarks>The file is loaded from the <see cref="Resources.TextFile.txt"/>.</remarks>
private static void ShowResource()
{
    // Getting text from embedded resource
}

Если я скомпилирую этот код и скомпилирую chm из полученной XML-документации, я получу следующее в журнале сборки:

  Warn: CachedResolveReferenceLinksComponent: Unknown reference link target '!:Resources.HelpTextFile.txt'.

А раздел замечаний:

The help file is loaded from the [!:Resources.TextFile.txt].

Если я действую как Агент Смит для ReSharper предлагает и заменит элемент на <see cref="Resources.TextFile"/> в журнале сборки:

Warn: CachedResolveReferenceLinksComponent: Unknown reference link target 'P:ProjectName.Properties.Resources.TextFile'.

А раздел «Замечания» в chm меняется на:

The help file is loaded from the HelpTextFile().

Итак, мой вопрос состоит из двух частей:

1. Правильно ли мое использование элемента для ссылки на ресурс?
2. Есть ли способ заставить sandcastle ссылаться на встроенный ресурс в генерируемых им файлах chm?

Answer 1

Вы можете использовать HTML-тег привязки для достижения того же результата. Это похоже на ссылку на файлы изображений с помощью тега в комментариях XML.

/// The resources are loaded from
/// <a href="../Resources.TextFile.txt">Resources.TextFile.txt</a>.

Включить файл ресурса в качестве элемента контента в проект. В приведенном выше примере предполагается, что он находится в корневой папке. HTML-файлы всегда находятся в папке ./html, поэтому необходимо перейти на один уровень вверх. Если вы поместите файл в подпапку вне корневой папки, добавьте его имя к цели href: "../FolderName/Resources.TextFile.txt".

Если вы применили патч Sandcastle Styles, вы можете использовать атрибут href вместо атрибута cref в теге . Информация о местоположении файла будет такой же.

/// The resources are loaded from
/// <see href="../Resources.TextFile.txt" />.

Eric