AutoModeCodeGenerator.Analyzers 1.0.1

AutoModeCodeGenerator.Analyzers

基于 Roslyn 的 C# 增量源生成器：用接口规格在编译期生成 SqlSugar / Admin.NET 风格 的 Entity / Dto / Create / Update / Detail / Search 等类型（数据形状；不生成 Service / Controller）。

当前版本：1.0.1.0

使用目的： 一份规格 → 多 CRUD 产物；按 mode 投影字段；对接现有 ORM + AppService，消灭六模式/外键样板。亦支持 .entity.json 声明式生成。

双主入口：（A）规格接口 + [AutoCodeCrudModes] / Relation / Morph → 六产物；（B）.entity.json → 声明式类型。共享 Emit。详见 AI 指南 §0·ARCHITECTURE。

CRUD 推荐： [AutoCodeCrudModes] + Relation / Morph / Column / Index；审计可用 InjectMarkerMembers。ClassStyle 默认 Poco；Record / Inpc 按需。

1.0.1： AutoCodeClassModes / *Str / CustomAttribute 软弃用（[Obsolete]，行为保留）。AppVeyor 发包格式 1.0.1.{build}。

目录

• 安装
• 1.0.1 破坏性变更（相对 1.0.0.17）
• 推荐：CRUD 预设
• Morph 字段变换
• 列 / 索引 / ModeFlags
• 注入 / SearchRange / CodeFix
• 手写六模式（Obsolete）
• 快速开始（最小示例）
• 核心概念
• 特性参考
• 诊断
• 从 entity.json 生成
• 验证与测试

安装

<PackageReference Include="AutoModeCodeGenerator.Analyzers" Version="1.0.1.0" PrivateAssets="all" />

PrivateAssets="all" 确保生成器仅参与编译，不传递到依赖项目的运行时引用。

可选 MSBuild 开关

包会自动导入 build/AutoModeCodeGenerator.Analyzers.props。可在消费项目的 PropertyGroup 中覆盖：

<PropertyGroup>
  
  <AutoModeGenerateEntityFiles>true</AutoModeGenerateEntityFiles>
  <AutoModeEntityFileSuffix>.entity.json</AutoModeEntityFileSuffix>
  
  <AutoModeSearchRangeTemplate>SearchRangeForStructValue&lt;{0}&gt;</AutoModeSearchRangeTemplate>
</PropertyGroup>

可选：将生成代码输出到磁盘

便于在 IDE 中查看生成结果：

<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
<CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>

1.0.1 破坏性变更（相对 1.0.0.17）

从 1.0.0.x 升级到 1.0.1.x 时请注意（Record / Inpc 语义）：

完整说明见仓库 CHANGELOG.md。

推荐：CRUD 预设

默认 Poco。用一行预设替代六行 AutoCodeClassModes；属性 Id 使用内置 AutoCodeCrud 常量。

using AutoCodeGenerator;

[AutoCodeCrudModes(EntityInterfaceTypes = [typeof(IEntityMarker)])]
public interface Product : IHasLongId
{
    [AutoCodeProperty(Ids = [AutoCodeCrud.Entity, AutoCodeCrud.Dto, AutoCodeCrud.Search])]
    string Name { get; set; }

    [AutoCodeRelation(TargetName = nameof(Category))]
    long Category { get; set; }
}

模式约定（预设默认值）

常用选项：OmitModes（如 AutoCodeCrudOmit.EntityOnly）、EntitySuffix（内控等可改为 "Entity"）、CreateUpdateDetailInheritDto。

合并规则： 同一 Id 的手写 AutoCodeClassModes 覆盖预设展开结果。

AutoCodeRelation

在外键属性上声明，默认展开：

1. {Name}Id → Entity / Dto / Search
2. Detail 类型投影（可空）
3. Search 类型投影
4. Entity 上的 Navigate 属性（默认 SqlSugar 字符串模板；IncludeNavigate = false 可关；NavigateAttribute 可换 EF 等）

共享 mixin

将 Id、审计字段放在基接口上，仅标 AutoCodeProperty（Ids 用 AutoCodeCrud.*）。

Samples：CrudCookbook/CrudProduct.cs。升级步骤见 UPGRADE.md。

Morph 字段变换

[AutoCodeMorph(Kind = AutoCodeMorphKind.File, CreateUpdateType = "UploadFileInput", DetailType = "FileOutput")]
string Receipt { get; set; }

[AutoCodeMorph(Kind = AutoCodeMorphKind.StringEnum, EnumType = nameof(PayStatus),
    EntityAttributes = [AutoCodeAttrMacros.SugarColumnIgnore],
    ApiAttributes = [AutoCodeAttrMacros.JsonIgnore])]
PayStatus Status { get; set; }

[AutoCodeProperty(Ids = [AutoCodeCrud.Entity, AutoCodeCrud.Dto])]
[AutoCodeMorph(Kind = AutoCodeMorphKind.SearchRange)]
DateTime Created { get; set; }

[AutoCodeMorph(Kind = AutoCodeMorphKind.StringArray)]
string Tags { get; set; }

类型与 EntityAttributes / ApiAttributes 均可项目级覆盖。约定模板：CONVENTIONS_TEMPLATE.md。

列 / 索引 / ModeFlags

[AutoCodeCrudModes(EntityInterfaceTypes = [typeof(ICreateTimeEntity<long>)])]
[AutoCodeIndex("IX_Raw_CreateTime", Spec = "CreateTime:Desc")]
[AutoCodeIndex(Name = "UK_Device", Unique = true, Columns = ["DeviceName"])]
public interface InboundRaw : IHasLongId, IHasCreateTime
{
    [AutoCodeProperty(ModeFlags = AutoCodeModeFlags.EntityDtoSearch)]
    [AutoCodeColumn(Length = 64)]
    string? DeviceName { get; set; }

    [AutoCodeProperty(ModeFlags = AutoCodeModeFlags.EntityDtoDetail)]
    [AutoCodeColumn(BigString = true)]
    string? PlatformWire { get; set; }
}

注意： EntityInterfaceTypes 不会自动投影属性。使用 ICreateTimeEntity 时必须有带 AutoCodeProperty 的 CreateTime mixin，否则 Mccj011（并最终 CS0535）。模板见 CONVENTIONS_TEMPLATE.md。

手写标准六模式会收到 Mccj012（Info）提示改用 AutoCodeCrudModes。

注入 / SearchRange / CodeFix

[AutoCodeCrudModes(
    EntityInterfaceTypes = [typeof(ICreateTimeEntity<long>)],
    InjectMarkerMembers = true,
    SearchRangeType = typeof(SearchRangeForStructValue<>))] // 亦可用 SearchRangeTemplate 字符串
public interface BootLog : IHasLongId { /* ... */ }

日期列宏：AutoCodeAttrMacros.SugarColumnDateTimeDbType（string.Format(..., "global::Your.DateTimeConverter")）。

手写六模式（Obsolete）

1.0.1 起 AutoCodeClassModes / *Str 带 [Obsolete]（error: false），行为保留。标准六模式请改用 AutoCodeCrudModes（或 Mccj012 Code Fix）。自定义 mode / 与预设同 Id 覆盖时仍可用 ClassModes。

using C = MyApp.AutoGeneratorConst;

[AutoCodeClassModes(Id = C.DtoId, Suffix = C.DtoSuffix)]
[AutoCodeClassModes(Id = C.EntityId, Suffix = C.EntitySuffix, InterfaceTypes = [typeof(IEntity<long>)])]
[AutoCodeClassModes(Id = C.CreateId, InheritStr = nameof(Product) + C.DtoSuffix, Suffix = C.CreateSuffix, SummaryPrefix = "创建")]
[AutoCodeClassModes(Id = C.UpdateId, InheritStr = nameof(Product) + C.DtoSuffix, Suffix = C.UpdateSuffix, SummaryPrefix = "更新")]
[AutoCodeClassModes(Id = C.DetailId, InheritStr = nameof(Product) + C.DtoSuffix, Suffix = C.DetailSuffix, SummaryPrefix = "详情")]
[AutoCodeClassModes(Id = C.SearchId, ToNullable = true, Suffix = C.SearchSuffix, SummaryPrefix = "搜索")]
public interface Product : IHasId<long>
{
    [AutoCodeProperty(Ids = [C.EntityId, C.DtoId, C.SearchId])]
    string Name { get; set; }
}

外键四段式（等价于 AutoCodeRelation）：

[AutoCodeProperty(Ids = [C.EntityId, C.DtoId, C.SearchId], Suffix = "Id")]
[AutoCodeProperty(Ids = [C.DetailId], PropertyTypeStr = nameof(Category) + C.DetailSuffix, IsNullable = true)]
[AutoCodeProperty(Ids = [C.SearchId], PropertyTypeStr = nameof(Category) + C.SearchSuffix)]
[AutoCodeProperty(
    Ids = [C.EntityId],
    PropertyTypeStr = nameof(Category) + C.EntitySuffix,
    IsNullable = true,
    Attributes = [$"global::SqlSugar.Navigate(global::SqlSugar.NavigateType.ManyToOne, nameof({nameof(Category)}Id))"])]
public long Category { get; set; }

快速开始（最小示例）

1. 在接口或类上添加 [AutoCodeClassModes]，指定唯一 Id 及生成选项。
2. 在需要导出的属性上添加 [AutoCodeProperty]，通过 Id / Ids 关联到对应的类模式。
3. 编译后，生成器输出 {命名空间}.{类型名}.g.cs。

#nullable enable

[AutoCodeGenerator.AutoCodeNullable(Type = AutoCodeGenerator.NullableEnum.Enable)]
[AutoCodeGenerator.AutoCodeClassModes(
    Id = "dto",
    Namespace = "MyApp.Models",
    Suffix = "Dto",
    ClassStyle = AutoCodeGenerator.ClassStyleEnum.Poco)]
public interface IUser
{
    [AutoCodeGenerator.AutoCodeProperty(Id = "dto")]
    string Name { get; set; }

    [AutoCodeGenerator.AutoCodeProperty(Id = "dto", IsNullable = true)]
    int Age { get; set; }
}

编译后生成类似：

namespace MyApp.Models
{
    public partial class IUserDto
    {
        public string Name { get; set; } = null!;
        public int? Age { get; set; }
    }
}

init / required 示例

[AutoCodeGenerator.AutoCodeClassModes(Id = "dto", Namespace = "MyApp.Models")]
public interface IProduct
{
    [AutoCodeGenerator.AutoCodeProperty(Id = "dto", IsInit = true, IsRequired = true)]
    string Name { get; set; }
}

生成属性类似：public required string Name { get; init; }（仅 Poco / Record；Inpc 忽略这两项）。

完整示例见仓库 TestModel.interface.cs。

核心概念

Id 关联机制

• AutoCodeClassModes(Id = "a1", ...) 定义一种生成模式。
• AutoCodeProperty(Id = "a1") 或 Ids = new[] { "a1", "a2" } 将属性绑定到一种或多种模式。
• 同一接口可配置多个 AutoCodeClassModes，一次定义生成多个不同命名空间/样式的类。
• 缺少或空白的 Id 会报告 Warning Mccj004 并跳过该模式；属性引用不存在的 Id 报告 Mccj005。

类样式（ClassStyle）

CRUD 与多数场景保持默认 Poco。Record / Inpc 按需选用（特性与 entity.json 均可）。

Inpc 可显式指定基类；省略时自动使用内置基类：

[AutoCodeClassModes(
    Id = "vm",
    ClassStyle = AutoCodeGenerator.ClassStyleEnum.Inpc,
    InheritType = typeof(AutoCodeGenerator.InpcPropertyBindableBaseAbstract))]

内置基类实现 INotifyPropertyChanged：SetValue 在值变化时触发 PropertyChanged。也可提供自己的基类（需提供兼容的 GetValue / SetValue / RaisePropertyChanged 成员）。

Record 构造函数参数名为属性名首字母小写（单字符属性加 @，如 X → @X）。

继承与接口成员

• 源类型继承的其他接口成员上的 AutoCodeProperty 也会参与生成。
• InheritAttribute = true 时，源属性上的非生成器 Attribute（如 [DisplayName]）会复制到生成类。

生成文件命名

特性参考

安装包后，生成器会自动注入 AutoCodeGenerator 命名空间下的特性定义，无需手动引用程序集。

AutoCodeCrudModesAttribute / AutoCodeCrud / AutoCodeRelationAttribute

见上文「推荐：CRUD 预设」。AutoCodeCrud 提供 mode Id 与默认 Suffix 常量；AutoCodeCrudOmit 为 Flags。

AutoCodeMorphAttribute / AutoCodeAttrMacros

见上文「Morph 字段变换」。

AutoCodeClassModesAttribute

标注在接口或类上，可多次使用。

AutoCodePropertyAttribute

标注在属性上。

AutoCodeNullableAttribute

标注在接口或类上，控制生成文件的 #nullable 指令（不可多次使用）。

NullableEnum 取值：

CustomAttributeAttribute

按 Id 为类或属性批量附加 Attribute 字符串，可与 AutoCodeClassModes / AutoCodeProperty 配合使用。

AccessibilityEnum

诊断

从 entity.json 生成

双主入口 B：声明式类型生成，与特性路径共享 Emit。当前不经 CrudModes / Relation / Morph 展开器；多 mode 与 ClassStyle 在 JSON 内直接声明。SqlSugar CRUD 六产物仍推荐入口 A（特性）。

将 JSON 文件标记为 AdditionalFiles，文件名以 .entity.json 结尾（或与 AutoModeEntityFileSuffix 一致）：

<AdditionalFiles Include="Models\Customer.entity.json" />

单类示例

{
  "$schema": "https://raw.githubusercontent.com/mccj/AutoModeCodeGenerator/main/src/AutoModeCodeGenerator.Analyzers/EntityFiles/entity.schema.json",
  "namespace": "MyApp.Entities",
  "className": "Customer",
  "classStyle": "Poco",
  "nullable": "enable",
  "summary": "Customer entity",
  "properties": [
    { "name": "Id", "type": "int", "summary": "主键" },
    { "name": "Name", "type": "string", "isNullable": true, "isInit": true, "isRequired": true }
  ]
}

多 mode 示例

省略根级单类配置、改用 modes 时，可一次生成多个目标类（行为对齐特性路径的多 AutoCodeClassModes）：

{
  "$schema": "https://raw.githubusercontent.com/mccj/AutoModeCodeGenerator/main/src/AutoModeCodeGenerator.Analyzers/EntityFiles/entity.schema.json",
  "nullable": "enable",
  "modes": [
    {
      "id": "dto",
      "namespace": "MyApp.Dtos",
      "className": "Customer",
      "suffix": "Dto",
      "classStyle": "Poco"
    },
    {
      "id": "rec",
      "namespace": "MyApp.Records",
      "className": "Customer",
      "suffix": "Rec",
      "classStyle": "Record"
    }
  ],
  "properties": [
    { "name": "Id", "type": "int", "ids": ["dto", "rec"] },
    { "name": "Name", "type": "string", "id": "dto" }
  ]
}

规则摘要：

• 无 modes 时：根级字段定义单个类（向后兼容）。
• 有 modes 时：每个 mode 必须有非空 id；类级字段可写在 mode 上，未写的可回退到根级同名字段。
• 属性未指定 id / ids 时，会进入所有 mode；指定后仅进入匹配的 mode。
• 输出仍为单个 {ClassName}.entity.g.cs（默认类名取自文件名）。

NuGet 包内附带 content/entity.schema.json。可将该文件复制到项目中，并在 JSON 里通过相对路径引用 $schema，以获得编辑器补全与校验。

完整示例见 TestModel.entity.json。

JSON 字段参考

根级 / 单类字段

modes[] 项

未在 mode 上声明的字段，解析时回退到根级同名字段。

properties[] 项

字段完整定义见包内 content/entity.schema.json 或仓库 entity.schema.json。

验证与测试

仓库提供 AutoModeCodeGenerator.Tests 项目，通过 Roslyn GeneratorDriver 在内存中验证生成结果与诊断行为：

dotnet test src/AutoModeCodeGenerator.Tests/AutoModeCodeGenerator.Tests.csproj

主要测试类：