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:
Then a comment like this:
- /// <summary>
- /// Represents a book in the library.
- /// </summary>
- public partial class Book
Will be output into the .xml file.
I tried putting documentation into the Model. Here is the designer view:
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:
- <#if (!ReferenceEquals(edmProperty.Documentation, null))
- {
- #>
- /// <summary>
- /// <#=edmProperty.Documentation.Summary#> – <#=edmProperty.Documentation.LongDescription#>
- /// </summary>
- <#}#>
After doing this I got the following in my Book.auto.cs class:
- /// <summary>
- /// ISBN – International Standard Book Number
- /// </summary>
- [DataMember]
- public string ISBN
Then my documentation can look like this:
The above was created using Sandcastle and the Sandcastle Help File Builder.
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?
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?
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!
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!
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)
{#>
///
///
///