The Joy of Excellence

XML Comments for Entity Framework

Technorati Tags: ,,,

HEADLINE: If I use the Entity Framework (Self Tracking Entities or EntityObjects) templates, how can I add XML Comments so that I can use Sandcastle and Sandcastle Help File Builder to generate the documentation for my libraries? Is there a way to modify the T4 templates so that I can access the property documentation? (The answer is yes)

This uses Microsoft Visual Studio 2010 Beta 2, Microsoft ADO.NET Entity Framework (EF) Feature Community Technology Preview 2, Sandcastle, and Sandcastle Help File Builder (SHFB)

Details:

If I turn on XML Documentation:

image

Then a comment like this:

Code Snippet
  1. /// <summary>
  2. /// Represents a book in the library.
  3. /// </summary>
  4. public partial class Book

Will be output into the .xml file.

I tried putting documentation into the Model. Here is the designer view:

clip_image004

However, these never seem to be output as the publicly visible comments (///) in the generated code.

To do that, add this in the template immediately above the property:

Code Snippet
  1. <#if (!ReferenceEquals(edmProperty.Documentation, null))
  2. {
  3. #>
  5. /// <summary>
  6. /// <#=edmProperty.Documentation.Summary#> – <#=edmProperty.Documentation.LongDescription#>
  7. /// </summary>
  8. <#}#>

After doing this I got the following in my Book.auto.cs class:

Code Snippet
  1. /// <summary>
  2. /// ISBN – International Standard Book Number
  3. /// </summary>
  4. [DataMember]
  5. public string ISBN

Then my documentation can look like this:

clip_image006

The above was created using Sandcastle and the Sandcastle Help File Builder.

Posted

in

by

Karl

Tags:

, , ,

Comments

5 responses to “XML Comments for Entity Framework”

  1. George Avatar
    George

    I’m trying to do this with the DbContext template. Any tips on where to place the above code snippet? The article says to add the code immediately above ‘the property’. So far I’ve been ridiculously unsuccessful modifying my template.

    Has anyone else working with DbContext T4 templates got this working?

    Reply
    1. karlz Avatar
      karlz

      I’ve downloaded the template but I’ve not worked with it yet.
      In the Self Tracking Entity template there is a section that starts with:
      region.Begin(“Primitieve Properties”);
      foreaeach (EdmProperty …)
      {
      <put the code snipit here>
      [DataMember]

      Is there not something like that in the DbContext T4 template?

      Reply
      1. George Avatar
        George

        Thanks for the reply Karlz! I found some similar code in the DbContext model template and gave it a try. I didn’t get any errors or warnings but the comments still don’t show up. I even tried editing the CS file and re-running the template just to make sure it was actually regenerating the code. So far, no luck but I’m determined to get this working.

        I’ll have to do some extra reading. I was hoping to learn as little as possible about these templates but it looks like I may need to dig a little deeper. I’m probably missing the obvious due to my lack of knowledge in this area. I’ll keep plugging away.

        Thanks again for blogging about this. I still have hope!

        Reply
        1. karlz Avatar
          karlz

          The only thing that comes to mind then are: 1) Are you using Visual Studio 10, and 2) Did you put the comments into the Model?
          By comments in the model I’m talking about opening the .edmx in the designer view and the selecting the field in question and going to the properties tab and filling out the two Documentation fields (Summary and Long Description) for the field in question. Save the .edmx and then

          I’m actually in the middle of another project that uses the Entity Framework. I wanted to do this, but hadn’t gottne to it yet. I just tried and it seems a bit tricky. One time I select “Run Custom Tool” and it did nothing. Moments later I got the message, “The file has changed on disk, do you want to reload?” And there was my comment!

          Reply
  2. Jim Avatar
    Jim

    Okay, this is really old, but I just found this to be really helpful. Thanks!

    The t4 may have changed since the original post. I added checking if the LongDescription is non-zero in length and, if so, putting it in the Remarks section. Here’s the code with a little bit of the preceding t4.

    ///
    ///
    ///
    0)
    {#>
    ///
    ///
    ///

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.