How to: Create an XML Documentation File Using CodeDOM

CodeDOM can be used to create code that generates XML documentation. The process involves creating the CodeDOM graph that contains the XML documentation comments, generating the code, and compiling the generated code with the compiler option that creates the XML documentation output.

To create a CodeDOM graph that contains XML documentation comments

  1. Create a CodeCompileUnit containing the CodeDOM graph for the sample application.

  2. Use the CodeCommentStatement constructor with the docComment parameter set to true to create the XML documentation comment elements and text.

    CodeTypeDeclaration class1 = new CodeTypeDeclaration("Class1");
    
    class1.Comments.Add(new CodeCommentStatement("<summary>", true));
    class1.Comments.Add(new CodeCommentStatement(
        "Create a Hello World application.", true));
    class1.Comments.Add(new CodeCommentStatement(
        @"<seealso cref=" + '"' + "Class1.Main" + '"' + "/>", true));
    class1.Comments.Add(new CodeCommentStatement("</summary>", true));
    
    // Add the new type to the namespace type collection.
    samples.Types.Add(class1);
    
    // Declare a new code entry point method.
    CodeEntryPointMethod start = new CodeEntryPointMethod();
    start.Comments.Add(new CodeCommentStatement("<summary>", true));
    start.Comments.Add(new CodeCommentStatement(
        "Main method for HelloWorld application.", true));
    start.Comments.Add(new CodeCommentStatement(
        @"<para>Add a new paragraph to the description.</para>", true));
    start.Comments.Add(new CodeCommentStatement("</summary>", true));
    

To generate the code from the CodeCompileUnit

  • Use the GenerateCodeFromCompileUnit method to generate the code and create a source file to be compiled.

    StreamWriter sourceFile = new StreamWriter(sourceFileName);
    provider.GenerateCodeFromCompileUnit(cu, sourceFile, null);
    sourceFile.Close();
    

To compile the code and generate the documentation file

  • Add the /doc compiler option to the CompilerOptions property of a CompilerParameters object and pass the object to the CompileAssemblyFromFile method to create the XML documentation file when the code is compiled.

    CompilerParameters opt = new CompilerParameters(new string[]{
                              "System.dll" });
    opt.GenerateExecutable = true;
    opt.OutputAssembly = "HelloWorld.exe";
    opt.TreatWarningsAsErrors = true;
    opt.IncludeDebugInformation = true;
    opt.GenerateInMemory = true;
    opt.CompilerOptions = "/doc:HelloWorldDoc.xml";
    
    CompilerResults results;
    
    LogMessage("Compiling with " + providerName);
    results = provider.CompileAssemblyFromFile(opt, sourceFileName);
    

The following code example creates a CodeDOM graph with documentation comments, generates a code file from the graph, and compiles the file and creates an associated XML documentation file.

using System;
using System.CodeDom;
using System.CodeDom.Compiler;
using System.IO;
using System.Text.RegularExpressions;

namespace BasicCodeDomApp
{
    class Program
    {
        static string providerName = "cs";
        static string sourceFileName = "test.cs";
        static void Main(string[] args)
        {
            CodeDomProvider provider = 
                CodeDomProvider.CreateProvider(providerName);

            LogMessage("Building CodeDOM graph...");

            CodeCompileUnit cu = new CodeCompileUnit();

            cu = BuildHelloWorldGraph();

            StreamWriter sourceFile = new StreamWriter(sourceFileName);
            provider.GenerateCodeFromCompileUnit(cu, sourceFile, null);
            sourceFile.Close();

            CompilerParameters opt = new CompilerParameters(new string[]{
                                      "System.dll" });
            opt.GenerateExecutable = true;
            opt.OutputAssembly = "HelloWorld.exe";
            opt.TreatWarningsAsErrors = true;
            opt.IncludeDebugInformation = true;
            opt.GenerateInMemory = true;
            opt.CompilerOptions = "/doc:HelloWorldDoc.xml";

            CompilerResults results;

            LogMessage("Compiling with " + providerName);
            results = provider.CompileAssemblyFromFile(opt, sourceFileName);

            OutputResults(results);
            if (results.NativeCompilerReturnValue != 0)
            {
                LogMessage("");
                LogMessage("Compilation failed.");
            }
            else
            {
                LogMessage("");
                LogMessage("Demo completed successfully.");
            }
            File.Delete(sourceFileName);
        }

        // Build a Hello World program graph using  
        // System.CodeDom types. 
        public static CodeCompileUnit BuildHelloWorldGraph()
        {
            // Create a new CodeCompileUnit to contain  
            // the program graph.
            CodeCompileUnit compileUnit = new CodeCompileUnit();

            // Declare a new namespace called Samples.
            CodeNamespace samples = new CodeNamespace("Samples");
            // Add the new namespace to the compile unit.
            compileUnit.Namespaces.Add(samples);

            // Add the new namespace import for the System namespace.
            samples.Imports.Add(new CodeNamespaceImport("System"));

            // Declare a new type called Class1.
            CodeTypeDeclaration class1 = new CodeTypeDeclaration("Class1");

            class1.Comments.Add(new CodeCommentStatement("<summary>", true));
            class1.Comments.Add(new CodeCommentStatement(
                "Create a Hello World application.", true));
            class1.Comments.Add(new CodeCommentStatement(
                @"<seealso cref=" + '"' + "Class1.Main" + '"' + "/>", true));
            class1.Comments.Add(new CodeCommentStatement("</summary>", true));

            // Add the new type to the namespace type collection.
            samples.Types.Add(class1);

            // Declare a new code entry point method.
            CodeEntryPointMethod start = new CodeEntryPointMethod();
            start.Comments.Add(new CodeCommentStatement("<summary>", true));
            start.Comments.Add(new CodeCommentStatement(
                "Main method for HelloWorld application.", true));
            start.Comments.Add(new CodeCommentStatement(
                @"<para>Add a new paragraph to the description.</para>", true));
            start.Comments.Add(new CodeCommentStatement("</summary>", true));

            // Create a type reference for the System.Console class.
            CodeTypeReferenceExpression csSystemConsoleType = 
                new CodeTypeReferenceExpression("System.Console");

            // Build a Console.WriteLine statement.
            CodeMethodInvokeExpression cs1 = new CodeMethodInvokeExpression(
                csSystemConsoleType, "WriteLine",
                new CodePrimitiveExpression("Hello World!"));

            // Add the WriteLine call to the statement collection.
            start.Statements.Add(cs1);

            // Build another Console.WriteLine statement.
            CodeMethodInvokeExpression cs2 = new CodeMethodInvokeExpression(
                csSystemConsoleType, "WriteLine", new CodePrimitiveExpression(
                "Press the ENTER key to continue."));

            // Add the WriteLine call to the statement collection.
            start.Statements.Add(cs2);

            // Build a call to System.Console.ReadLine.
            CodeMethodInvokeExpression csReadLine = 
                new CodeMethodInvokeExpression(csSystemConsoleType, "ReadLine");

            // Add the ReadLine statement.
            start.Statements.Add(csReadLine);

            // Add the code entry point method to 
            // the Members collection of the type.
            class1.Members.Add(start);

            return compileUnit;
        }
        static void LogMessage(string text)
        {
            Console.WriteLine(text);
        }

        static void OutputResults(CompilerResults results)
        {
            LogMessage("NativeCompilerReturnValue=" +
                results.NativeCompilerReturnValue.ToString());
            foreach (string s in results.Output)
            {
                LogMessage(s);
            }
        }
    }
}

The code example creates the following XML documentation in the HelloWorldDoc.xml file.

<?xml version="1.0" ?> 
<doc>
  <assembly>
    <name>HelloWorld</name> 
  </assembly>
  <members>
    <member name="T:Samples.Class1">
      <summary>
        Create a Hello World application. 
        <seealso cref="M:Samples.Class1.Main" /> 
      </summary>
    </member>
    <member name="M:Samples.Class1.Main">
      <summary>
        Main method for HelloWorld application. 
        <para>Add a new paragraph to the description.</para> 
      </summary>
    </member>
  </members>
</doc>

  • This code example requires the FullTrust permission set to execute successfully.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft