EntityFramework Core 2.x （ef core）在遷移中自動生成數據庫表和列說明

在項目開發中有沒有用過拼音首字母做列名或者接手這樣的項目？

看見xmspsqb（項目審批申請表）這種表名時是否有一種無法抑制的想肛了取名的老兄的衝動？

更坑爹的是這種數據庫沒有文檔（或者文檔老舊不堪早已無用）也沒有數據庫內部說明，是不是很無奈？

但是，凡事就怕有但是，有些表和列名字確實太專業（奇葩），用英文不是太長就是根本不知道用什麼（英文差……），似乎也只能用拼音。好吧，那就用吧，寫個說明湊活用用。這個時候問題就來了，如何用sql生成表和列說明？在ef core中又怎樣生成表和列說明？

以sqlserver爲例。

1、使用ssms管理器編輯說明：不瞎的都知道吧。

2、使用sql生成說明：

　　添加　　

　　exec sys.sp_addextendedproperty
　　@name=N'MS_Description'
　　, @value=N'說明'
　　, @level0type=N'SCHEMA'
　　, @level0name=N'dbo'
　　, @level1type=N'TABLE'
　　, @level1name=N'表名'
　　, @level2type=N'COLUMN'
　　, @level2name=N'列名'

　　紅字根據情況修改，需要注意，如果說明已經存在會報錯。如果需要添加的是表說明，那麼@level2type 和 @level2name填NULL即可。

　　刪除

　　exec sys.sp_dropextendedproperty
　　@name=N'MS_Description'
　　, @level0type=N'SCHEMA'
　　, @level0name=N'dbo'
　　, @level1type=N'TABLE'
　　, @level1name=N'表名'
　　, @level2type=N'COLUMN'
　　, @level2name=N'列名'

　　需要注意，如果說明不存在會報錯。其他同上。

　　很好，只需要這兩個內置存儲過程就可以用sql管理說明了，修改雖然也有，但是先刪再加也一樣，就不寫了。還有一個遺留問題，上面的存儲過程會報錯，後面的sql就得不到執行，這需要解決一下，思路很直接，查詢下是否存在，存在的話先刪再加，不存在就直接加。

　　查詢說明是否存在　

　　select exists (
　　select t.name as tname,c.name as cname, d.value as Description
　　from sysobjects t
　　left join syscolumns c
　　on c.id=t.id and t.xtype='U' and t.name<>'dtproperties'
　　left join sys.extended_properties d
　　on c.id=d.major_id and c.colid=d.minor_id and d.name = 'MS_Description'
　　where t.name = '表名' and c.name = '列名' and d.value is not null)

　　紅字根據情況修改，如果要查詢的是表說明，刪除下劃線部分即可。

　　不錯，判斷問題也解決了，直接使用sql管理基本上也就夠用了，那麼如果使用ef core託管數據庫該怎麼辦呢？思路也很清晰，使用ef遷移。在遷移中管理sql，MigrationBuilder.Sql(string sql)方法可以在遷移中執行任何自定義sql。把上面的sql傳給方法就可以讓ef遷移自動生成說明，並且生成的獨立遷移腳本文件也包含說明相關sql。

　　問題看似解決了，但是（又是但是），這個解決方案實在是太難用了。1、這樣的字符串沒有智能提示和代碼着色，怎麼寫錯的都不知道。2、後續管理困難，很可能跟數據庫文檔一樣的下場，沒人維護更新，隨着版本推移逐漸淪爲垃圾。3、不好用！不優雅！

　　接下來就是個人思考嘗試後得到的解決方案：

　　1、將說明分散到說明對象的臉上，讓查閱和修改都能隨手完成，降低維護成本，利用C#的特性可以優雅的解決這個問題。

 1     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Enum | AttributeTargets.Property | AttributeTargets.Field, Inherited = true, AllowMultiple = false)]
 2     public class DbDescriptionAttribute : Attribute
 3     {
 4         /// <summary>
 5         /// 初始化新的實例
 6         /// </summary>
 7         /// <param name="description">說明內容</param>
 8         public DbDescriptionAttribute(string description) => Description = description;
 9 
10         /// <summary>
11         /// 說明
12         /// </summary>
13         public virtual string Description { get; }
14     }

　　2、讀取特性並應用到遷移中。不過我並不打算讓遷移直接讀取特性，首先在遷移過程中實體類型並不會載入，從模型獲取實體類型結果是null，需要自己想辦法把模型類型傳入遷移。其次我希望遷移能時刻與模型匹配，ef遷移會生成多個遷移類代碼，追蹤整個實體模型的變更歷史，而特性一旦修改，就會丟失舊的內容，無法充分利用ef遷移的跟蹤能力。基於以上考慮，可以把模型的說明寫入模型註解，ef遷移會將模型註解寫入遷移快照。最後就是在適當的時機讀取特性並寫入註解，很顯然，這個時機就是OnModelCreating方法。

 1         public static ModelBuilder ConfigDatabaseDescription(this ModelBuilder modelBuilder)
 2         {
 3             foreach (var entityType in modelBuilder.Model.GetEntityTypes())
 4             {
 5                 //添加表說明
 6                 if (entityType.FindAnnotation(DbDescriptionAnnotationName) == null && entityType.ClrType?.CustomAttributes.Any(
 7                         attr => attr.AttributeType == typeof(DbDescriptionAttribute)) == true)
 8                 {
 9                     entityType.AddAnnotation(DbDescriptionAnnotationName,
10                         (entityType.ClrType.GetCustomAttribute(typeof(DbDescriptionAttribute)) as DbDescriptionAttribute
11                         )?.Description);
12                 }
13 
14                 //添加列說明
15                 foreach (var property in entityType.GetProperties())
16                 {
17                     if (property.FindAnnotation(DbDescriptionAnnotationName) == null && property.PropertyInfo?.CustomAttributes
18                             .Any(attr => attr.AttributeType == typeof(DbDescriptionAttribute)) == true)
19                     {
20                         var propertyInfo = property.PropertyInfo;
21                         var propertyType = propertyInfo?.PropertyType;
22                         //如果該列的實體屬性是枚舉類型，把枚舉的說明追加到列說明
23                         var enumDbDescription = string.Empty;
24                         if (propertyType.IsEnum
25                             || (propertyType.IsDerivedFrom(typeof(Nullable<>)) && propertyType.GenericTypeArguments[0].IsEnum))
26                         {
27                             var @enum = propertyType.IsDerivedFrom(typeof(Nullable<>))
28                                 ? propertyType.GenericTypeArguments[0]
29                                 : propertyType;
30 
31                             var descList = new List<string>();
32                             foreach (var field in @enum?.GetFields() ?? new FieldInfo[0])
33                             {
34                                 if (!field.IsSpecialName)
35                                 {
36                                     var desc = (field.GetCustomAttributes(typeof(DbDescriptionAttribute), false)
37                                         .FirstOrDefault() as DbDescriptionAttribute)?.Description;
38                                     descList.Add(
39                                         $@"{field.GetRawConstantValue()} : {(desc.IsNullOrWhiteSpace() ? field.Name : desc)}");
40                                 }
41                             }
42 
43                             var isFlags = @enum?.GetCustomAttribute(typeof(FlagsAttribute)) != null;
44                             var enumTypeDbDescription =
45                                 (@enum?.GetCustomAttributes(typeof(DbDescriptionAttribute), false).FirstOrDefault() as
46                                     DbDescriptionAttribute)?.Description;
47                             enumTypeDbDescription += enumDbDescription + (isFlags ? " [是標誌位枚舉]" : string.Empty);
48                             enumDbDescription =
49                                 $@"( {(enumTypeDbDescription.IsNullOrWhiteSpace() ? "" : $@"{enumTypeDbDescription}; ")}{string.Join("; ", descList)} )";
50                         }
51 
52                         property.AddAnnotation(DbDescriptionAnnotationName,
53                             $@"{(propertyInfo.GetCustomAttribute(typeof(DbDescriptionAttribute)) as DbDescriptionAttribute)
54                                 ?.Description}{(enumDbDescription.IsNullOrWhiteSpace() ? "" : $@" {enumDbDescription}")}");
55                     }
56                 }
57             }
58 
59             return modelBuilder;
60         }

　　在OnModelCreating方法中調用ConfigDatabaseDescription方法即可將說明寫入模型註解。其中的關鍵是AddAnnotation這個ef core提供的API，不清楚1.x和ef 6.x有沒有這個功能。其中DbDescriptionAnnotationName就是個名稱，隨便取，只要不和已有註解重名即可。可以看到，這個方法同時支持掃描並生成枚舉類型的說明，包括可空枚舉。

　　3、在遷移中讀取模型註解並生成說明。有了之前的準備工作，到這裏就好辦了。

 1         public static MigrationBuilder ApplyDatabaseDescription(this MigrationBuilder migrationBuilder, Migration migration)
 2         {
 3             var defaultSchema = "dbo";
 4             var descriptionAnnotationName = ModelBuilderExtensions.DbDescriptionAnnotationName;
 5 
 6             foreach (var entityType in migration.TargetModel.GetEntityTypes())
 7             {
 8                 //添加表說明
 9                 var tableName = entityType.Relational().TableName;
10                 var schema = entityType.Relational().Schema;
11                 var tableDescriptionAnnotation = entityType.FindAnnotation(descriptionAnnotationName);
12 
13                 if (tableDescriptionAnnotation != null)
14                 {
15                     migrationBuilder.AddOrUpdateTableDescription(
16                         tableName,
17                         tableDescriptionAnnotation.Value.ToString(),
18                         schema.IsNullOrEmpty() ? defaultSchema : schema);
19                 }
20 
21                 //添加列說明
22                 foreach (var property in entityType.GetProperties())
23                 {
24                     var columnDescriptionAnnotation = property.FindAnnotation(descriptionAnnotationName);
25 
26                     if (columnDescriptionAnnotation != null)
27                     {
28                         migrationBuilder.AddOrUpdateColumnDescription(
29                             tableName,
30                             property.Relational().ColumnName,
31                             columnDescriptionAnnotation.Value.ToString(),
32                             schema.IsNullOrEmpty() ? defaultSchema : schema);
33                     }
34                 }
35             }
36 
37             return migrationBuilder;
38         }

　　在遷移的Up和Down方法末尾調用ApplyDatabaseDescription方法即可取出模型註解中的說明並生成和執行相應的sql。

　　至此，一個好用的數據庫說明管理就基本完成了。因爲這個方法使用了大量ef core提供的API，所以基本上是完整支持ef core的各種實體映射，實測包括與實體類名、屬性名不一致的表名、列名，（嵌套的）Owned類型屬性（類似ef 6.x的複雜類型屬性 Complex Type）、表拆分等。可以說基本上沒有什麼後顧之憂。這裏的sql是以sqlserver爲例，如果使用的是mysql或其他關係數據庫，需要自行修改sql以及AddOrUpdateColumnDescription和AddOrUpdateTableDescription的邏輯。

　　其中Owned類型屬性在生成遷移時可能會生成錯誤代碼，導致編譯錯誤CS1061 "ReferenceOwnershipBuilder"未包含"HasAnnotation"的定義且……，只需要把HasAnnotation替換成HasEntityTypeAnnotation即可。估計是微軟的老兄粗心沒注意這個問題。

　　ps：爲什麼不直接使用Description或者DisplayName之類的內置特性而要使用自定義特性，因爲Description在語義上是指廣泛的說明，並不能明確表明這是數據庫說明，同時避免與現存代碼糾纏不清影響使用，爲加強語義性，使用新增的自定義特性。

　　ps2：爲什麼不使用xml註釋文檔，因爲這會讓這個功能產生對/doc編譯選項和弱類型文本的依賴，甚至需要對文檔配置嵌入式資源，也會增加編碼難度，同時會影響現存代碼的xml註釋，爲避免影響現存代碼，對非代碼和編譯器不可檢查行爲的依賴，保證代碼健壯性，不使用xml文檔註釋。

　　效果預覽：