首先在实体框架模型中添加文档到生成的代码 [英] Add documentation to generated code in entity framework model first

问题描述

自VS 2010以来我一直在使用Entity Framework模型。当我构建项目时，EF会生成一个包含所有实体的Model.Designer.cs文件。此设计器文件还包含添加到EDMX文件中的实体的文档。

I have been using Entity Framework model first since VS 2010. When I build my project, EF generates a Model.Designer.cs file containing all entities. This designer file also contains the documentation added to the entities in the EDMX file.

当在VS 2012中创建新的EF模型第一个项目时，Model.tt文件是添加到我的EDMX文件。此T4模板为我的模型中的每个实体生成一个文件。不幸的是，EDMX文件中的文档不会在生成的代码中使用。

When I created a new EF model first project in VS 2012, a Model.tt file is added to my EDMX file. This T4 template generates a single file for every entity in my model. Unfortunately, the documentation from the EDMX file is not used in the generated code.

我真的很喜欢让我的模型记录下来，所以IntelliSense在使用它时显示。目前我发现的唯一解决方法是删除Model.tt和生成的类文件，并重新启动我的EDMX文件上的代码生成。这恢复了我从VS 2010使用的行为。但是，我宁愿每个实体有一个单独的文件。

I really like having my model documented so IntelliSense shows up when using it. The only workaround I have found so far is remove the Model.tt and the generated class files and turning the code generation on my EDMX file back on. This reverts back to the behaviour I am used from VS 2010. However, I would prefer having a separate file per entity.

有没有办法（最好使用VS工具和而不必修改VS附带的任何文件），以便在生成的单个类文件中包含EDMX文件中的文档？

Is there any way (preferably using VS tools and without having to modify any files that ship with VS) to include the documentation from the EDMX file in the generated single class files?

编辑：为了进一步说明我的问题，是一个快速的例子。

To further illustrate my problem, here is a quick example.

我们的模型如下所示：

Let's say my model looks like this:

我已经突出显示了在Id属性的属性窗口中输入文档的部分。

I have highlighted the part where I entered the documentation in the Properties window of the Id property.

这是EDMX文件中实体的样子：

This is what the entity looks like in the EDMX file:

    <EntityType Name="Entity1">
      <Key>
        <PropertyRef Name="Id" />
      </Key>
      <Property Type="Int32" Name="Id" Nullable="false" annotation:StoreGeneratedPattern="Identity" >
        <Documentation>
          <Summary>This is documentation for the ID property.</Summary>
        </Documentation>
      </Property>
    </EntityType>

Model.tt生成的类（Entity1.cs）如下所示：

The generated class (Entity1.cs) by Model.tt looks like this:

public partial class Entity1
{
    public int Id { get; set; }
}

但是当我打开我的模型的代码生成时，这是什么该实体看起来像在Model.Designer.cs中：

But when I turn on the code generation for my model, this is what the entity looks like in Model.Designer.cs:

/// <summary>
/// No Metadata Documentation available.
/// </summary>
[EdmEntityTypeAttribute(NamespaceName="Model1", Name="Entity1")]
[Serializable()]
[DataContractAttribute(IsReference=true)]
public partial class Entity1 : EntityObject
{
    #region Factory Method

    /// <summary>
    /// Create a new Entity1 object.
    /// </summary>
    /// <param name="id">Initial value of the Id property.</param>
    public static Entity1 CreateEntity1(global::System.Int32 id)
    {
        Entity1 entity1 = new Entity1();
        entity1.Id = id;
        return entity1;
    }

    #endregion

    #region Simple Properties

    /// <summary>
    /// This is documentation for the ID property.
    /// </summary>
    [EdmScalarPropertyAttribute(EntityKeyProperty=true, IsNullable=false)]
    [DataMemberAttribute()]
    public global::System.Int32 Id
    {
        get
        {
            return _Id;
        }
        set
        {
            if (_Id != value)
            {
                OnIdChanging(value);
                ReportPropertyChanging("Id");
                _Id = StructuralObject.SetValidValue(value, "Id");
                ReportPropertyChanged("Id");
                OnIdChanged();
            }
        }
    }
    private global::System.Int32 _Id;
    partial void OnIdChanging(global::System.Int32 value);
    partial void OnIdChanged();

    #endregion

}

所以你请参阅：Model.Designer.cs包含我的自定义文档字符串这是ID属性的文档。而Entity1.cs没有。但是，如果有多个实体，Model.Designer.cs可能会变得很大，并且调试到这个文件有点慢。我希望有几个小文件（每个实体一个），但仍然保留EDMX文件中生成的代码中的文档。

So you see: Model.Designer.cs contains my custom documentation string "This is documentation for the ID property." while Entity1.cs does not. However, Model.Designer.cs can get quite big if there are many entities and debugging into this file is somewhat slow. I'd prefer having several small files (one per entity), but still preserve the documentation from the EDMX file in the generated code.

推荐答案

我想你必须修改T4文件。我有同样的问题，阅读T4文件，并尝试按照这里的说明： http://karlz.net/blog/index.php/2010/01/16/xml-comments-for-entity-framework/

I think you'll have to modified the T4 file. I've got the same problem and read through the T4 file a bit, and tried to follow the instruction here: http://karlz.net/blog/index.php/2010/01/16/xml-comments-for-entity-framework/

但是，我们使用的是VS 2012，并且该指令似乎没有100％的工作。我最终在T4文件的末尾更改了属性生成代码，它的工作原理就是我想要的。更改在CodeStringGenerator.Property（）和CodeStringGenerator.NavigationProperty（）

However, we're using VS 2012 and the instruction doesn't seem to work 100%. I ended up changing the property generation code at the end of the T4 file and it works exactly how I wanted it to be. The changes are in CodeStringGenerator.Property() and CodeStringGenerator.NavigationProperty()

public string Property(EdmProperty edmProperty)
{
    string doc = "";
    if (edmProperty.Documentation != null)
    {
        doc = string.Format(
        CultureInfo.InvariantCulture,
        "\n\t\t/// <summary>\n\t\t/// {0} - {1}\n\t\t/// </summary>\n\t\t",
        edmProperty.Documentation.Summary ?? "",
        edmProperty.Documentation.LongDescription ?? "");
    }

    return doc + string.Format(
        CultureInfo.InvariantCulture,
        "{0} {1} {2} {{ {3}get; {4}set; }}",
        Accessibility.ForProperty(edmProperty),
        _typeMapper.GetTypeName(edmProperty.TypeUsage),
        _code.Escape(edmProperty),
        _code.SpaceAfter(Accessibility.ForGetter(edmProperty)),
        _code.SpaceAfter(Accessibility.ForSetter(edmProperty)));
}

public string NavigationProperty(NavigationProperty navigationProperty)
{
    var endType = _typeMapper.GetTypeName(navigationProperty.ToEndMember.GetEntityType());
    string doc = "";
    if (navigationProperty.Documentation != null)
    {
        doc = string.Format(
        CultureInfo.InvariantCulture,
        "\n\t\t/// <summary>\n\t\t/// {0} - {1}\n\t\t/// </summary>\n\t\t",
        navigationProperty.Documentation.Summary ?? "",
        navigationProperty.Documentation.LongDescription ?? "");
    }

    return doc + string.Format(
        CultureInfo.InvariantCulture,
        "{0} {1} {2} {{ {3}get; {4}set; }}",
        AccessibilityAndVirtual(Accessibility.ForProperty(navigationProperty)),
        navigationProperty.ToEndMember.RelationshipMultiplicity == RelationshipMultiplicity.Many ? ("ICollection<" + endType + ">") : endType,
        _code.Escape(navigationProperty),
        _code.SpaceAfter(Accessibility.ForGetter(navigationProperty)),
        _code.SpaceAfter(Accessibility.ForSetter(navigationProperty)));
}

请注意，它不适用于类文档，因此您必须做像实体和复杂类型这样的东西

Note that it won't work with class documentation, so you have to do something like this with entity and complex type

<#=codeStringGenerator.UsingDirectives(inHeader: false)#>
<#if (!ReferenceEquals(entity.Documentation, null))
{
#>
/// <summary>
/// <#=entity.Documentation.Summary#> – <#=entity.Documentation.LongDescription#>
/// </summary>
<#}#>
<#=codeStringGenerator.EntityClassOpening(entity)#>

这篇关于首先在实体框架模型中添加文档到生成的代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！