Add navigation property comments

[jdanielpa]

Is it possible to add an option to comment navigation properties? Right now I can add MS_Description as an extended property on table fields and that results in the comments for each property after scaffolding. However, I can't find a way to add comments to navigation properties created on the class. Is this even possible?

[R4ND3LL]

I'll get back to you soon on this. Came down with COVID symptoms on Friday.

[jdanielpa]

Thanks for the update and hopefully you have a quick recovery!

[R4ND3LL]

Design package v1.2.0 now contains support for inheritance, table splitting, comments, and other features. The Editor VSIX package has also been updated accordingly.

The approach taken here is the ability to add annotations to any element in the entity hierarchy (table, property, navigation). Whatever annotations are specified in the JSON will be applied to the corresponding entity element during the scaffolding phase. This means that EFR now supports any feature that is customizable via annotations in EF, which is virtually everything (EF stores all configurations as annotations).

There is one catch. The T4 templates may need to be updated to support the annotation feature you're after because the default templates do not expect some kinds of annotations to be generated in the scaffolding phase.

EDMX comments are now read (from Summary/Long Description), stored in the JSON as an annotation, and will be applied to the EF Core entity or property as a comment. You can also specify the comment using the editor by adding it to the annotations table. The annotation key is "Relational:Comment".

No changes to the T4 is necessary for entity and property comments. However, for navigation comments, the T4 does not have the code generation element to output the comment.

Update your T4 with the comment generator code and it should work fine. It should resemble something like:

        if (!string.IsNullOrEmpty(navigation.GetComment()))
        {
#>
    /// <summary>
    /// <#= code.XmlComment(navigation.GetComment(), indent: 1) #>
    /// </summary>

[jdanielpa]

Sorry for the delay in response. I have been travelling but I will be working on this next week. I will keep you posted on my testing and progress. Thanks!

[jdanielpa]

I am testing the comments on navigation properties and I see a two issues:

1. When I edit the annotation, I cannot see what I am editing:

2. I have added your code in the template for Navigation property comments:

   foreach (var navigation in EntityType.GetNavigations().Where(o => o.DeclaringEntityType == EntityType))
   {
       WriteLine("");
   
        if (!string.IsNullOrEmpty(navigation.GetComment()))
       {
   #>
   /// <summary>
   /// <#= code.XmlComment(navigation.GetComment(), indent: 1) #>
   /// </summary>
   <#
       }
       if (Options.UseDataAnnotations)
       {
           foreach (var dataAnnotation in navigation.GetDataAnnotations(annotationCodeGenerator))
           {
   #>
   <#= code.Fragment(dataAnnotation) #>
   <#
           }
       }

   This causes scaffolding to fail. Is this not the correct place to put the code? I am getting: Object reference not set to an instance of an object.

[R4ND3LL]

For the editor issue, I added a separate "Comments" text box, which allows for multi-line editing. Multi-line editing is not possible in that grid. New version of VSIX is on the way via the build pipeline right now.

I replicated the object ref error when scaffolding nav comments. The following code works instead (for the EntityType.t4):

        string comment = navigation?.FindAnnotation("Relational:Comment")?.Value as string;
        if (!string.IsNullOrEmpty(comment))
        {
#>
    /// <summary>
    /// <#= code.XmlComment(comment, indent: 1) #>
    /// </summary>
<#
        }  

Seems to be an issue in EF Core - not happy about doing GetComment() for a navigation.