Supporting Custom tags in Sandcastle

Sandcastle supports C# (and VB) xml tags for developer documentation comments. The list of c# tags are available at We added the following new custom nDoc tags in November CTP (


1.            <overloads>

2.            <preliminary>

3.            <threadsafety>

4.            <note>


These custom tags are supported in nDoc and you can see the tags under tag reference section at


This blog provides details on how to define your custom tags. To support custom tags the user can modify the presentation transforms (XSLT) that are shipped with Sandcastle. The following steps provides details:


1)         Add the custom tag to the code in C# file [test.cs]:



            /// <customTag>This is a custom tag.</customTag>

            public class StoredNumber




2)         Compile the C# file and extract the /// comments to, say comments.xml.



            csc /t:library /doc:comments.xml test.cs


            The custom tag will be included in the XML.


3)         Update main_sandcastle.xsl with the following:


            <xsl:template name=body>

  <!–Add this depending on where we want our custom tag to be displayed–>

  <xsl:apply-templates select=/document/comments/customTag />



<xsl:template match=customTag>

  <!–Customstyle can be defined in Presentaion.css stylesheet–>

  <div class=CustomStyle>

    <xsl:apply-templates />




            The resulting page for the topic would look like the following with custom tag at the top of the page:

Custom Tags
























Comments (10)

  1. gfraiteur says:

    Hi Anand,

    This feature calls the following question: if I modify Sandcastle XSL files, can I distribute the modified version? The current answer is, I think, no, because the file is licensed as a part of the software, under  "don’t modify" and "don’t distribute" clauses. It would be necessary to release the XSL files under a more liberal license, or, the best, under the public domain.

    Otherwise the ‘custom tags’ feature cannot be used legally…


  2. Garry Trinder says:

    Good point Gael. I will check this with Microsoft legal contact and will let you know.

    We cannot meet all the custom tags and this is the bext way to go. I will see if we can exclude the presentation tansforms from the license.


  3. CoqBlog says:

    Un post sur le blog de Sandcastle explique comment gérer les tags personnalisés, en particulier la modification

  4. About two weeks ago, Microsoft have released a new CTP for Sandcastle . For those still in the dark,

  5. CoqBlog says:

    Un post sur le blog de Sandcastle explique comment gérer les tags personnalisés, en particulier la modification

  6. The DocProject 1.9.0 Release Candidate is now available on CodePlex. I’m still working on updating the

  7. Hello, anything new about the Licence thing here?

  8. Anonymous says:

    I too would be interested in learning about any updates on this issue. Is it maybe possible to pass names of files that contain additional XSLT fragments to the Sandcastle command line, so the original XSLTs wouldn't have to be modified? I hope this issue can finally be solved after 6 years.

  9. Renato Guarilha says:

    Hi Anand, first of all, congratulations. Your post was very usefull, And I've acomplished my goals and have included some custom information along my Class Anotations.

    Now, I've some complicated issues with custom tag in class member anotations like custom tags in class properties.

    Do you have some example in how to do that?

    Thanks in advance.