.net XML Documentation Comment include directive in sandcastle not adding to help file

Question

Have an interesting one. I'm documenting a method using XML documentation comments in C#. I want to use the directive to include all the contents of a referenced file. I am documenting a piece of code which receives a string formatted as an xml document, and I want to include the XSD file in the parameter documentation.

This works fine in that the XML generated by Visual Studio is as I expect. Here's a snippet of the XML:

    /// <param name="xml">XML string - see Test.xsd <include file="XSD/Test.xsd" path="/*"/> After file include</param>

However, when I use Sandcastle to generate a help file from this, the contents of the xsd file are not shown, but Sandcastle does not report any errors. I've tried to use the file name as relative to where the help files are as well, i.e.

but then Visual Studio complains it can't find the file. I put them in both places and still the included file does not appear.

Any ideas?

Answer 1

The include tag is processed at compiler time, so the generated XML file should contain all of its referred contents. Hence you have to put your XSD folder relative to the C# source file, then the compiler won't show any errors. After this, Sandcastle will be able to create the help file from the single XML document.