UnitGenerator 使用教程

UnitGenerator 使用教程

UnitGenerator C# Source Generator to create value-object, inspired by units of measure. 项目地址: https://gitcode.com/gh_mirrors/un/UnitGenerator

1. 项目介绍

UnitGenerator 是一个 C# 源代码生成器，用于创建受度量单位启发的值对象（Value Object）。它支持所有算术运算符和序列化，旨在帮助开发者更安全、更高效地处理特定类型的数据。UnitGenerator 通过生成代码来确保值对象的类型安全，防止类型间的错误赋值，并支持算术运算和比较操作。

2. 项目快速启动

2.1 安装

首先，通过 NuGet 安装 UnitGenerator：

Install-Package UnitGenerator

2.2 创建值对象

以下是一个简单的示例，展示如何使用 UnitGenerator 创建一个值对象 UserId：

using UnitGenerator;

[UnitOf(typeof(int))]
public readonly partial struct UserId
{
}

2.3 使用值对象

生成的 UserId 值对象将自动实现 IEquatable<UserId> 接口，并支持类型安全的比较和赋值操作：

var userId1 = new UserId(123);
var userId2 = new UserId(456);

bool isEqual = userId1 == userId2; // 比较两个 UserId 对象
int primitiveValue = userId1.AsPrimitive(); // 获取原始值

3. 应用案例和最佳实践

3.1 游戏中的 HP 值对象

在游戏中，HP（生命值）通常需要支持算术运算，但不应允许与其他类型混淆。使用 UnitGenerator 可以轻松实现这一点：

[UnitOf(typeof(int), UnitGenerateOptions.ArithmeticOperator | UnitGenerateOptions.ValueArithmeticOperator | UnitGenerateOptions.Comparable | UnitGenerateOptions.MinMaxMethod)]
public readonly partial struct Hp
{
}

使用示例：

var hp1 = new Hp(100);
var hp2 = new Hp(50);

var newHp = hp1 + hp2; // 支持算术运算
var minHp = Hp.Min(hp1, hp2); // 支持 Min 方法

3.2 数据库序列化

UnitGenerator 还支持多种序列化方式，如 MessagePack、Json 等，确保值对象在序列化和反序列化过程中保持类型安全：

[UnitOf(typeof(int), UnitGenerateOptions.MessagePackFormatter)]
public readonly partial struct UserId
{
}

4. 典型生态项目

UnitGenerator 可以与其他 C# 生态项目无缝集成，如：

• Entity Framework Core: 支持值对象的自动转换和数据库映射。
• Dapper: 支持值对象的类型安全查询和结果映射。
• System.Text.Json: 支持值对象的 JSON 序列化和反序列化。

通过这些集成，UnitGenerator 可以帮助开发者在整个应用栈中保持类型安全，减少潜在的错误。

---

通过本教程，您应该已经掌握了如何使用 UnitGenerator 创建和使用值对象，并了解了其在实际项目中的应用场景和最佳实践。希望 UnitGenerator 能够帮助您在 C# 开发中更高效、更安全地处理数据。

UnitGenerator C# Source Generator to create value-object, inspired by units of measure. 项目地址: https://gitcode.com/gh_mirrors/un/UnitGenerator