This project has moved. For the latest updates, please go here.

Add XML comments to EF6-generated *.cs files

Note: The program described on this page does not illustrate the use of TDS, but it is related to the example shown in TDS Example – Editing a Text Template File, in which the DbDictSample.xml file contains comments that may be used to automatically update an EDMX file.  (I have not yet posted the software to do this, as nobody has asked for it yet, but there are other ways to update those comments, as shown below.)

Also, it’s only fair to warn you that, in developing the utility, I had only imperfect knowledge of the structure and contents of the generated *.tt file.  The example database contains a variety of structures, various types of joins and navigation properties, and the comments for these appear to be properly translated.  I did not find a suitable location for comments on functions, so you may need to handle those separately.  If you find a defect in my code, please post a comment to “ISSUES” so that I can address it.

 

Purpose

This page presents a straightforward means to add XML comments to the C# entities (types, data members, function members) defined in the *.cs files generated by Entity Framework 6 from an EDMX Entity Data Model file.

I present it in the form of a C# source-code file, so that (1) you may inspect it to satisfy yourself that it is safe to run, as it does make changes to your file system, and (2) you may modify it as needed to adapt it to your needs.  I expect that not much customization will be needed, as it basically just grabs the <Documentation> elements from the CSDL in your EDMX file and pastes them, formatted as XML comments, into the appropriate *.cs source-code files.

Having populated the *.cs files with XML comments, you can then see the comments in the form of IntelliSense pop-ups while accessing the C# types generated by the compiler, as well as in the Visual Studio Object Browser.

 

How to use it

Set up EDMX

First, you need an EDMX file with some comments.  In Visual Studio (I use Visual Studio 2013 Express), create a new project and add to your project an ADO.NET Entity Data Model file (*.edmx) containing elements (tables, fields, etc.) matching at least part of your database.  (The example EDMX that I show here is avaiable at Model05.edmx .)

Add comments to your EDMX model (this example already contains some).  You my do this either via the Documentation properties in the Entity Data Model's GUI, as shown here, where the PublisherId field (in the database) or Property (in the C# type definitions) is selected.  The text of the comments belonging in its Long Description and Summary properties may be entered into the Properties window; in this example, they are the strings beginning with “210”:

Ef6DiagramDoc

I numbered these (“210” in this example) to help identify them in the XML comments.  Laugh at them if you wish; I know that they're not very informative, but they can be tracked, and anyway they are destined to be replaced by more extensive comments from a file structured like DbDictBooks.xml .

Alternatively, you might edit the corresponding <Documentation> elements in the XML view of the same Entity Data Model, as seen below.  I prefer this, as Visual Studio’s XML editor makes it fairly easy to locate and modify these elements, but either method is effective.

Ef6XmlDoc

 

Generate the *.tt files

With the EDMX file’s GUI open in Visual Studio, set its Code Generation Strategy property to “T4” (if it's not already equal to that).

To avoid possible conflicts with existing generated files, delete any files depending on the EDMX file in Visual Studio’s Solution Explorer.

Right-click on the GUI and select “Add Code Generation Item”; select “EF 6.x DbContext Generator”.  Choose a name for it; in this example, we’ll go with the default name of “Model1.tt”.

Click on “Add”; presently some *.tt files should appear below the *.edmx file’s entry in Solution Explorer.  We shall modify only the *.tt file, not the *.Context.tt .

 

Run the updating utility

Copy the following two files to the file folder containing your project, where your *.edmx file and, therefore, its generated *.tt files are located: InsertCommentsCall.txt and InsertComments.cs . You might need to edit the InsertCommentsCall.txt file to specify the correct path for the csc.exe C# compiler, and, if you wish to use it as a batch file, rename it to "InsertCommentsCall.bat".

What we do now is to compile and run a program that will read the *.tt file, add code to generate the XML comments, and replace the *.tt file.  You can easily reconstruct the *.tt file, as shown above, but you may choose to make a backup copy of it.  (If you’re curious about what the changes look like, you may compare your updated *.tt file with the backup… but they’ll probably be kind of boring.)

Open a Command Prompt window and CD (“change directory” command) to the folder where the EDMX file is located.

If you wish to review the instructions, use command “InsertCommentsCall”.

To update the *.tt file, assuming it’s called “Model1.tt”, use command “InsertCommentsCall Model1.tt”.

If line “Error level = 0” appears, the update apparently worked.

Synchronize files

Model1.tt should now be up to date, but not its generated files.  Right-click on Model1.tt in Solution Explorer, and click on “Run Custom Tool”.  (The custom tool should be “TextTemplatingFileGenerator”.)

If any of the *.cs files are open in Visual Studio, you’ll likely see a pop-up asking if you wish to update the files that are open for editing.  Click on “Yes to all”.

Let’s look at the code in generated file Book.cs that defines the Book.PublisherId property.  Glory be!  There seem to be some XML comments (tagged with my “210” label) attached to it now:

  /// <summary>
/// 210 Book.PubId summary
/// </summary>
/// <remarks>
/// 210 Book.PublisherId long descr
/// </remarks>
    public int PublisherId { get; set; }

 

Results

With the comments in place, you may see the corresponding pop-ups (<Summary> information only) while writing code,

IntelliSense01

or while reading existing code,

IntelliSense02

or (both <Summary> and <LongDescription> contents) in the Object Browser:

IntelliSense03

This information allows you to see the basics of the usage of the entities without having to examine their source code.  One substantial limitation is that there is no obvious (to me) way to document the parameters of functions; that’s left as an exercise for the reader (you).  Sorry.  Actually, I’m not now documenting anything relating to functions, maybe can do that in a later release, but don’t hold your breath waiting.

Last edited Sep 2, 2014 at 1:18 AM by vjohns, version 12