小技巧 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 推送到資料庫中即可。

至此關於 小技巧 EntityFrameworkCore 實現 CodeFirst 通過模型生成資料庫表時自動攜帶模型及欄位註釋信息 就講解完了，有任何不明白的，可以在文章下麵評論或者私信我，歡迎大家積極的討論交流，有興趣的朋友可以關註我目前在維護的一個 .NET 基礎框架項目，項目地址如下
https://github.com/berkerdong/NetEngine.git
https://gitee.com/berkerdong/NetEngine.git