小技巧 EntityFrameworkCore 實現 CodeFirst 透過模型生成資料庫表時自動攜帶模型及欄位註釋資訊

張曉棟發表於2022-12-15
Framework模型資料庫

今天分享自己在專案中用到的一個小技巧，就是使用 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

相關文章