技巧 EntityFrameworkCore 實現 CodeFirst 通過模型生成數據庫表時自動攜帶模型及字段註釋信息

今天分享自己在項目中用到的一個小技巧，就是使用 EntityFrameworkCore 時我們在通過代碼去 Update-Database 生成數據庫時如何自動將代碼模型上的註釋和字段上的註釋攜帶到數據庫中，方便後續在數據庫直接查看各個表和各個字段的含義。

實現效果如下： 可以看到我們每張表都有明確的註釋信息

選中表進入設計模式也可以直接看到各個字段註釋

在查看錶數據的時候，鼠標放在字段欄上同樣也可以顯示我們爲字段設置的註釋信息

 

 

我上面截圖用的數據庫管理工具是 Navicat ,各個數據庫工具的呈現UI方式可能有所不同。

---

熟悉微軟官方 EntityFrameworkCore 文檔的小夥伴這個時候肯定會想到下面兩個東西

 

當然直接爲表或者模型手動指定 Comment 屬性就可以實現我們上面的效果了，但是我們想要的並不是這樣，因爲我們在開發過程中往往給代碼已經寫過一次註釋了，像下面的類

 

我們其實已經爲 TOrder 模型寫過註釋了，甚至他內部的每個字段我們都寫了註釋，這樣寫註釋的好處在於外部代碼調用類時在代碼編輯器中引用到模型或者字段時都可以顯示註釋信息出來，方便後續的代碼維護。

有過同樣經歷的小夥伴這時候肯定就會想到，這邊的註釋沒法直接帶入數據庫，我們今天要解決的就是這個問題，將代碼上的註釋自動賦值給 Comment 屬性實現自動生成數據庫表和字段的註釋。

想要實現這點，首先我們需要爲放置數據庫模型類的代碼類庫啓用 XML 文件生成，同時設置取消 1591 的警告，這個操作如果配置過 WebAPI Swagger 文檔的小夥伴肯定很熟悉，其實都是一樣的目的，就是爲了項目在生成時自動生成模型的註釋信息到XML文件中，因爲註釋信息我們的代碼在編譯的時候是會直接忽略的，所以並不能通過代碼的某個屬性來獲取寫在註釋中的信息，所以我們選擇開啓 XML 描述文件生成，然後通過解析這個文件就可以獲取到我們想要的註釋信息。

可以在 visual studio 中選中類庫右擊屬性，調整如下兩個值

也可以直接選中類庫後右擊選擇標記項目文件，編輯如下信息

<GenerateDocumentationFile>True</GenerateDocumentationFile>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <NoWarn>1591</NoWarn>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <NoWarn>1591</NoWarn>
</PropertyGroup>

準備工作完成之後，接下來是我們的 GetEntityComment 方法，這是一個靜態方法，用於解析 XML 文件獲取指定類和字段的註釋，代碼如下，我這裏直接將這個方法寫在了 DatabaseContext 裏面，大家可以按照自己的喜好放置。

其中 path 就是我們類庫文檔xml文件的位置，我這裏默認是項目當前目錄下的，文件默認名稱就是類庫的名稱，我這裏是 Repository.xml ，大家需要按照自己的實際情況進行調整。

using System.Xml;

namespace Repository.Database
{
    public class DatabaseContext : DbContext
    {

        public static string GetEntityComment(string typeName, string? fieldName = null, List<string>? baseTypeNames = null)
        {
            var path = Path.Combine(AppContext.BaseDirectory, "Repository.xml");
            XmlDocument xml = new();
            xml.Load(path);
            XmlNodeList memebers = xml.SelectNodes("/doc/members/member")!;

            Dictionary<string, string> fieldList = new();

            if (fieldName == null)
            {
                var matchKey = "T:" + typeName;

                foreach (object m in memebers)
                {
                    if (m is XmlNode node)
                    {
                        var name = node.Attributes!["name"]!.Value;

                        var summary = node.InnerText.Trim();

                        if (name == matchKey)
                        {
                            fieldList.Add(name, summary);
                        }
                    }
                }

                return fieldList.FirstOrDefault(t => t.Key.ToLower() == matchKey.ToLower()).Value ?? typeName.ToString().Split(".").ToList().LastOrDefault()!;
            }
            else
            {

                foreach (object m in memebers)
                {
                    if (m is XmlNode node)
                    {
                        string name = node.Attributes!["name"]!.Value;

                        var summary = node.InnerText.Trim();

                        var matchKey = "P:" + typeName + ".";
                        if (name.StartsWith(matchKey))
                        {
                            name = name.Replace(matchKey, "");

                            fieldList.Remove(name);

                            fieldList.Add(name, summary);
                        }

                        if (baseTypeNames != null)
                        {
                            foreach (var baseTypeName in baseTypeNames)
                            {
                                if (baseTypeName != null)
                                {
                                    matchKey = "P:" + baseTypeName + ".";
                                    if (name.StartsWith(matchKey))
                                    {
                                        name = name.Replace(matchKey, "");
                                        fieldList.Add(name, summary);
                                    }
                                }
                            }
                        }
                    }
                }

                return fieldList.FirstOrDefault(t => t.Key.ToLower() == fieldName.ToLower()).Value ?? fieldName;
            }
        }
    }

}

有了上面的方法我們就只要在對 DatabaseContext.OnModelCreating 方法稍加改造即可就能實現我們本次的目的。

我這裏添加了 if DEBUG 標記用來控制只有在開發模式纔會執行設置表備註和字段備註的代碼，在線上運行時並不會進入這一部分邏輯

protected override void OnModelCreating(ModelBuilder modelBuilder)
{

    foreach (var entity in modelBuilder.Model.GetEntityTypes())
    {
        modelBuilder.Entity(entity.Name, builder =>
        {

#if DEBUG
            //設置表的備註
            builder.ToTable(t => t.HasComment(GetEntityComment(entity.Name)));

            List<string> baseTypeNames = new();
            var baseType = entity.ClrType.BaseType;
            while (baseType != null)
            {
                baseTypeNames.Add(baseType.FullName!);
                baseType = baseType.BaseType;
            }
#endif

            foreach (var property in entity.GetProperties())
            {

#if DEBUG
                //設置字段的備註
                property.SetComment(GetEntityComment(entity.Name, property.Name, baseTypeNames));
#endif

                //設置字段的默認值 
                var defaultValueAttribute = property.PropertyInfo?.GetCustomAttribute<DefaultValueAttribute>();
                if (defaultValueAttribute != null)
                {
                    property.SetDefaultValue(defaultValueAttribute.Value);
                }
            }
        });
    }
}

樣就算完成了，我們嘗試去執行 Add-Migration 命令，然後觀察生成的文件，就會發現已經包含我們的註釋信息了，然後直接 Update-Database 推送到數據庫中即可。

 

轉自：https://zhuanlan.zhihu.com/p/592092034

 

注我的個人公衆號，每日更新，獲取更多技術知識