Bread.Enum 1.0.3

Bread.Enum（Source Generator 使用指南）

Bread.Enum 是一个基于 Source Generator 的枚举增强库：

• 使用 [BreadEnum] 标记枚举；
• 编译期生成高性能、AOT 友好的枚举访问代码；
• 对外统一通过 BreadEnum 与扩展方法调用。

说明：当前 API 使用 Label / GetLabels / TryFromLabel 命名。

适用场景

• Native AOT / Trim 场景下，希望减少反射依赖；
• 希望提供稳定、统一的枚举访问 API（名称、标签、解析、定义判断）；
• 需要给枚举值附加展示文案（如中文名、UI 文案）。

安装

只需要安装 一个包：

• Bread.Enum

Bread.Enum.Core 会作为依赖自动引入；Source Generator 也会随包自动生效。

快速开始

using Bread.Enum;

[BreadEnum]
public enum LogLevel
{
    [Label("追踪")]
    Trace = 0,

    [Label("调试")]
    Debug = 1,

    [Label("信息")]
    Info = 2,

    [Label("警告")]
    Warn = 3,

    [Label("错误")]
    Error = 4,
}

API 总览

BreadEnum 静态方法

• TEnum[] GetValues<TEnum>()
• string[] GetNames<TEnum>()
• string[] GetLabels<TEnum>()
• bool IsDefined<TEnum>(int value)
• bool TryParse<TEnum>(string? text, out TEnum value, bool ignoreCase = false)
• bool TryFromLabel<TEnum>(string? text, out TEnum value, bool ignoreCase = false)

扩展方法

• string ToName<TEnum>(this TEnum value)
• string ToLabel<TEnum>(this TEnum value)

用法示例

1) 获取定义值、名称、标签

var values = BreadEnum.GetValues<LogLevel>();
var names = BreadEnum.GetNames<LogLevel>();
var labels = BreadEnum.GetLabels<LogLevel>();

2) 定义判断

var ok2 = BreadEnum.IsDefined<LogLevel>(3);   // true
var ok3 = BreadEnum.IsDefined<LogLevel>(99);  // false

3) 名称解析

if (BreadEnum.TryParse<LogLevel>("warn", out var level, ignoreCase: true))
{
    // level == LogLevel.Warn
}

4) 标签解析

if (BreadEnum.TryFromLabel<LogLevel>("警告", out var level))
{
    // level == LogLevel.Warn
}

5) 扩展方法

var level = LogLevel.Warn;
var name = level.ToName();   // "Warn"
var text = level.ToLabel();  // "警告"

LabelAttribute 规则

• 可用于枚举字段（AttributeTargets.Field）；
• 支持重复标注（AllowMultiple = true）；
• 如果同一个枚举值上有多个 [Label]，只取最后一个；
• 未标注 [Label] 时，默认回退到枚举成员名。

示例：

[BreadEnum]
public enum Status
{
    [Label("草稿")]
    [Label("待提交")]
    Draft = 0,
}

// Draft.ToLabel() == "待提交"

生成代码说明

标记 [BreadEnum] 后，会在编译期生成两类代码：

1. 每个枚举的内部 helper（internal，实现细节，不建议直接使用）；
2. 统一分发入口 BreadEnum + 扩展方法 ToName() / ToLabel()。

因此业务代码可保持统一调用风格，不需要记忆每个枚举对应的 helper 类型名。

常见问题

Q1：为什么没有生成代码？

请检查：

• 枚举是否添加了 [BreadEnum]；
• 项目是否成功编译；
• 是否已安装 Bread.Enum 包；
• 枚举是否定义在可编译的 C# 源集中（而非被条件编译排除）。

Q2：TryFromLabel 能否按名称回退解析？

当前 TryFromLabel 仅按 Label 文本匹配。名称解析请使用 TryParse。

最小示例（完整）

using Bread.Enum;

[BreadEnum]
public enum Fruits
{
    [Label("苹果")]
    Apple = 1,

    [Label("香蕉")]
    Banana = 2,
}

var values = BreadEnum.GetValues<Fruits>();
var names = BreadEnum.GetNames<Fruits>();
var labels = BreadEnum.GetLabels<Fruits>();

var okByName = BreadEnum.TryParse<Fruits>("Apple", out var f1);
var okByLabel = BreadEnum.TryFromLabel<Fruits>("香蕉", out var f2);

var name = Fruits.Apple.ToName();
var label = Fruits.Apple.ToLabel();