Euonia.Core
2026.5.0
dotnet add package Euonia.Core --version 2026.5.0
NuGet\Install-Package Euonia.Core -Version 2026.5.0
<PackageReference Include="Euonia.Core" Version="2026.5.0" />
<PackageVersion Include="Euonia.Core" Version="2026.5.0" />
<PackageReference Include="Euonia.Core" />
paket add Euonia.Core --version 2026.5.0
#r "nuget: Euonia.Core, 2026.5.0"
#:package Euonia.Core@2026.5.0
#addin nuget:?package=Euonia.Core&version=2026.5.0
#tool nuget:?package=Euonia.Core&version=2026.5.0
Euonia.Core
Euonia.Core 是 Euonia 框架的基础库,提供一组必备的、与具体框架解耦的通用构建模块——集合、反射辅助、扩展方法、异步线程原语、释放工具、异常类型与常用工具类——这些模块被 Euonia 下其他所有包复用。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.*(部分工具按惯例直接放入System/ 全局命名空间) - NuGet 包:
Euonia.Core - 开源:依据仓库内
LICENSE许可发布
安装
通过 NuGet 安装:
dotnet add package Euonia.Core
快速开始
直接使用库中的类型,无需额外配置:
using Nerosoft.Euonia;
var snowflakeId = ObjectId.Snowflake(); // 时间有序的唯一 ID
命名空间导航
| 命名空间 | 内容 |
|---|---|
(全局命名空间 + System) |
断言、Optional<T>、ID 生成、单例/对象池、弱引用、异常类型、扩展方法等 |
Nerosoft.Euonia.Collections |
双端队列、类型列表、可观测分组、分页集合、树等 |
Nerosoft.Euonia.Reflection |
类型内省、反射读写、枚举辅助、程序集加载 |
Nerosoft.Euonia.Threading |
AsyncLock、信号量、事件、监视器、AsyncContext 等异步原语 |
Nerosoft.Euonia.Threading.Interop |
将 WaitHandle / .NET 事件转为 Task |
Nerosoft.Euonia.Disposing |
同步/异步幂等释放原语 |
Nerosoft.Euonia.Security |
用户主体、声明类型、账号/凭据异常 |
Nerosoft.Euonia.Windows |
ICommand 实现(DelegateCommand、GenericCommand) |
System.ComponentModel.DataAnnotations |
Guid、集合元素数量校验特性 |
核心类型
高频入口的一张速查表,逐条说明见后续各节:
| 类型 | 命名空间 | 作用 |
|---|---|---|
Check / CheckResult<TValue> |
全局 | 参数断言与可链式校验结果 |
Optional<T> |
System |
显式表达「有值 / 无值」,避免 null 语义歧义 |
ObjectId / ObjectId<T> |
全局 | 统一 ID 类型,支持 Snowflake / ULID / Guid / 随机值 |
Singleton<T> / ObjectPool<T> |
System |
进程级单例容器与对象池 |
DisposableObject |
System |
幂等的同步/异步释放基类 |
Weak<T> / WeakEventManager |
System |
弱引用与弱事件 |
DequeCollection<T> / TypeList<T> |
Nerosoft.Euonia.Collections |
双端队列、类型列表 |
Reflect / PropertyAccessorCache<T> |
Nerosoft.Euonia.Reflection |
反射读写与访问器缓存 |
AsyncLock / AsyncSemaphore / AsyncLazy<T> |
Nerosoft.Euonia.Threading |
异步协调原语 |
UserPrincipal / UserClaimTypes |
Nerosoft.Euonia.Security |
当前用户主体与声明常量 |
Extensions |
全局 | 字符串、集合、反射、Task 等扩展方法 |
全局命名空间与 System
以下工具类按惯例直接放到全局命名空间或 System 命名空间(using System; 即可用,无需额外引入)。
断言与校验
Check
断言工具类,条件不满足时抛出异常:
Check.Ensure(list != null && list.Count > 0, "list 不能为空");
var item = Check.EnsureNotNull(value, nameof(value));
var code = Check.EnsureNotNullOrEmpty(code, nameof(code), maxLength: 16, minLength: 2);
Check.EnsureIsMatch(email, nameof(email), @"^[^@\s]+@[^@\s]+$");
Check.EnsureAssignableTo<Animal>(typeof(Dog), nameof(type));
Check.EnsureLengthInRange(name, "name", maxLength: 50);
CheckResult<TValue>
携带值与校验状态的结果对象,可链式处理:
var result = Check.Ensure(42, v => v > 0); // IsValid == true
result.Success(v => Console.WriteLine($"ok: {v}"))
.Failure(v => Console.WriteLine($"bad: {v}"));
if (result.IsValid)
{
int value = result; // 隐式转换为 TValue
}
ExceptionAssert
按条件抛出指定类型异常:
ExceptionAssert.ThrowIf<ArgumentOutOfRangeException>(count < 0, "count 必须大于等于 0");
ExceptionAssert.ThrowIf<InvalidOperationException>(notReady,
() => new InvalidOperationException("未就绪"));
ExceptionAssert.ThrowIf<NotSupportedException>(unsupported);
Invariant
仅在 DEBUG 构建下生效的不变量断言(Release 中被编译移除):
Invariant.Require(_state == State.Ready, "状态必须为 Ready");
Optional<T>
可空值的容器(有值时保证非空):
Optional<string> maybe = Optional<string>.OfNullable(GetNameOrNull());
maybe.IfPresent(n => Console.WriteLine(n)); // 有值才执行
string name = maybe.Or("guest"); // 默认值
int length = maybe.Select(s => s.Length).Or(-1); // 链式转换
string value = maybe.GetOrThrow<InvalidOperationException>(
() => new InvalidOperationException("缺失"));
Check(全局、非泛型断言之补充)
见上文 Check 一节。另外还有:
CheckResult<TValue>、ExceptionAssert、Invariant
均已包含在使用示例中,此处从略。
Clock
Unix 时间戳辅助:
long ms = Clock.GetUnixTimestampMillis();
long ticks = Clock.GetUnixTimestampTicks();
long then = Clock.ToUnixTimestampMillis(new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc));
ID 生成
ObjectId 与 ObjectId<T>
可包装 int / long / Guid / string 的值类型 ID,支持双向隐式转换,并提供多种 ID 生成器入口:
ObjectId snowflake = ObjectId.Snowflake(); // long 雪花 ID
ObjectId ulid = ObjectId.Ulid(); // 26 位 ULID 字符串
ObjectId guid = ObjectId.NewGuid(GuidType.SequentialAtEnd); // SQL Server 风格顺序 Guid
ObjectId random = ObjectId.Random(); // 随机字符串 ID
ObjectId id = 42; // long -> ObjectId
long back = id; // ObjectId -> long
ObjectId<Guid> gid = Guid.NewGuid(); // 泛型变体
Guid g = gid;
GuidType
Guid 生成策略枚举:Empty、Simple(随机 v4)、SequentialAsString(MySQL/PostgreSQL 风格)、SequentialAsBinary(Oracle 风格)、SequentialAtEnd(SQL Server 风格)。
单例与对象池
Singleton<T>
var svc = Singleton<MyService>.Get(() => new MyService());
MyService same = Singleton<MyService>.Instance;
ObjectPool<T> 与 IObjectPoolPolicy<T>
sealed class ListPolicy : IObjectPoolPolicy<List<int>>
{
public List<int> CreateNew() => new();
public bool Return(List<int> value) { value.Clear(); return true; }
}
var pool = new ObjectPool<List<int>>(new ListPolicy());
var list = pool.Lease();
try { list.Add(1); }
finally { pool.Return(list); }
生命周期、弱引用与事件
DisposableObject / DisposedEventArgs
提供 Disposed 事件与终结器兜底的抽象基类:
sealed class Resource : DisposableObject
{
private Stream? _stream;
protected override void Dispose(bool disposing)
{
if (disposing) _stream?.Dispose();
}
}
using var r = new Resource();
r.Disposed += (s, e) => Console.WriteLine($"Disposed, hash={e.HashCode}");
Weak<T> 与 WeakEventManager
var weak = new Weak<MyClass>(instance);
if (weak.Target is { } alive)
{
alive.DoWork();
}
AsyncEventHandler<TEventArgs> 与 Empty、Unit
bool isEmpty = Empty.Value.ToString() == ""; // true
Task unitTask = Unit.Task; // 已完成的任务
LikeOperator 与 TextCaseType / TextTrimType
bool a = LikeOperator.LikeString("Hello, World!", "hello*"); // true
bool b = LikeOperator.LikeString("abc", "a?c"); // true
string trimmed = " text ".Trim(TextTrimType.Both);
string camel = "hello_world".ToCamelCase(); // "helloWorld"
EnumHelper 与 EnumParser<T>、Reflect(见下方 Reflection 章节)
RequestContext
HTTP 请求上下文载体:
var ctx = new RequestContext
{
Method = "GET",
Path = "/api/orders",
Headers = new Dictionary<string, string> { ["Authorization"] = "Bearer abc" }
};
string auth = ctx.Authorization; // "Bearer abc"
其它
ShortUniqueId
Hashids 风格的短 ID 编码器:
var codec = new ShortUniqueId(salt: "my-key", minHashLength: 8);
string hash = codec.Encode(12345); // 例如 "Mz4ZQJkX"
long decoded = codec.DecodeSingleInt64(hash); // 12345
ObjectId / ObjectId<T>、UlidGenerator、GuidGenerator、RandomId
见上方「ID 生成」一节。
Nerosoft.Euonia.Collections
using Nerosoft.Euonia.Collections;
DequeCollection<T>
环形缓冲实现的双端队列,两端 O(1) 进出队,同时实现 IList<T>:
var deque = new DequeCollection<string>();
deque.AddToBack("b");
deque.AddToFront("a"); // [a, b]
deque.InsertRange(2, new[] { "c", "d" }); // [a, b, c, d]
string first = deque.RemoveFromFront(); // "a"
string last = deque.RemoveFromBack(); // "d"
deque[0] = "B";
string[] snapshot = deque.ToArray(); // ["B", "c"]
TypeList / TypeList<T>
仅允许"可赋值给基类型"的类型集合:
class Animal { }
class Dog : Animal { }
class Cat : Animal { }
var types = new TypeList<Animal>();
types.AddType<Dog>();
types.TryAddType<Dog>(); // false,已存在
bool hasDog = types.ContainsType<Dog>(); // true
types.RemoveType<Cat>();
ObservableGroup / ReadOnlyObservableGroup / ObservableGroupedCollection
可观测分组集合(每个组本身是 ObservableCollection + 不可变 Key):
var group = new ObservableGroup<string, int>("A", new[] { 1, 2, 3 });
group.Add(4);
string key = group.Key; // "A"
var grouped = new ObservableGroupedCollection<char, string>(
words.GroupBy(w => w[0]));
grouped.Add(new ObservableGroup<char, string>('x', new[] { "xray" }));
PageableCollection / ViewCollection
分页 / 视图集合:
var page = new PageableCollection<int>(new[] { 1, 2, 3, 4 })
{
PageNumber = 2,
PageSize = 2,
TotalCount = 4
};
page.StartPosition; // 3
page.EndPosition; // 4
page.PageCount; // 2
var view = new ViewCollection<string>(items, totalCount: 120);
view.TotalCount; // 120
其它
TreeView<TEntity>(树节点)、EquatableReadOnlyList<T>(按元素比较相等性)、ReadOnlyObservableGroup、ObservableGroupedCollection 等,API 详见源码与下文"反射/工具"章节示例。
Nerosoft.Euonia.Reflection
using Nerosoft.Euonia.Reflection;
类型内省:
var isDerived = typeof(Dog).IsSubclassOf(typeof(Animal));
var isGeneric = typeof(List<int>).IsAssignableToGenericType(typeof(IList<>)); // true
Reflect / Reflect<TTarget>
从 Lambda 表达式提取 PropertyInfo / MethodInfo,并支持读写属性值(含点分隔路径):
class Address { public string City { get; set; } }
class Person
{
public string Name { get; set; }
public Address Address { get; set; }
public void Work() { }
}
var person = new Person { Name = "Alice", Address = new Address { City = "Rome" } };
Reflect.SetValue(person, "Bob", p => p.Name);
object name = Reflect.GetValue(person, p => p.Name); // "Bob"
object city = Reflect.GetValue(person, typeof(Person), "Address.City"); // "Rome"
Reflect.SetValue(person, typeof(Person), "Address.City", "Paris");
TypeHelper / EnumHelper / EnumParser<T>
int n = TypeHelper.CoerceValue<int, string>("42"); // 42
var color = TypeHelper.CoerceValue<ConsoleColor>(typeof(string), "Red");
var desc = EnumHelper.GetCustomerAttribute<DescriptionAttribute>(Status.Active);
if (EnumParser<DayOfWeek>.TryParse("Friday", out var day)) { }
AssemblyHelper / AssemblyLoadContextManager
var types = AssemblyHelper.GetAllTypes(typeof(string).Assembly);
var assemblies = AssemblyHelper.LoadAssemblies(AppContext.BaseDirectory,
SearchOption.TopDirectoryOnly)-var
PropertyAccessorCache<T>
缓存属性的 Lambda 访问器表达式:
LambdaExpression expr = PropertyAccessorCache<Person>.Get(nameof(Person.Name));
// expr 形如 p => p.Name
Nerosoft.Euonia.Threading
所有协调原语均返回 AwaitableDisposable<T>,请始终使用 using (await x.LockAsync()) 形式。
AsyncLock
不可重入的异步互斥锁:
private readonly AsyncLock _mutex = new();
public async Task DoStuffAsync()
{
using (await _mutex.LockAsync())
{
await Task.Delay(TimeSpan.FromSeconds(1));
}
}
AsyncSemaphore
异步计数信号量:
var semaphore = new AsyncSemaphore(2apsed);
using (await semaphore.LockAsync()) // 占一个槽位
{
// 最多 2 个并发调用者
}
await semaphore.WaitAsync();
try { /* ... */ }
finally { semaphore.Release(); }
AsyncAutoResetEvent / AsyncManualResetEvent
var are = new AsyncAutoResetEvent();
are.Set();
await are.WaitAsync(); // 已置位则立即返回并自动复位
var mre = new AsyncManualResetEvent();
Task waiter = mre.WaitAsync();
mre.Set(); // 所有等待者完成
await waiter;
mre.Reset(); // 复位后新等待者再次阻塞
AsyncLazy<T>
线程安全、可直接 await 的异步惰性初始化:
var lazy = new AsyncLazy<int>(async () =>
{
await Task.Delay(100);
return 42;
}, AsyncLazyFlags.RetryOnFailure);
int answer = await lazy;
AsyncMonitor 与 AsyncConditionVariable
var monitor = new AsyncMonitor();
using (await monitor.EnterAsync())
{
while (!IsReady)
await monitor.WaitAsync(); // 等待期间释放监视器
monitor.Pulse(); // 唤醒一个等待者
}
AsyncCountdownEvent
var cde = new AsyncCountdownEvent(2);
Task allDone = cde.WaitAsync();
cde.Signal();
cde.Signal(); // 归零 -> allDone 完成
await allDone;
AsyncProducerConsumerQueue / AsyncCollection
var queue = new AsyncProducerConsumerQueue<int>(maxCount: 5);
await queue.EnqueueAsync(10);
int value = await queue.DequeueAsync();
queue.CompleteAdding();
foreach (var item in queue.GetConsumingEnumerable()) { }
PauseToken / PauseTokenSource
协作式暂停:
var source = new PauseTokenSource();
var pauseToken = source.Token;
async Task WorkerAsync()
{
while (true)
{
await pauseToken.WaitWhilePausedAsync(); // 未暂停时立即返回
await DoWorkAsync();
}
}
source.IsPaused = true; // 工作循环在此阻塞
source.IsPaused = false; // 恢复
DeferralManager / IDeferralSource
让事件参数声明"异步处理器仍在运行":
var manager = new DeferralManager();
using (manager.DeferralSource.GetDeferral())
{
await ProcessSlowlyAsync(); // 离开作用域才算完成
}
await manager.WaitForDeferralsAsync();
State 与 StatefulMutex
绑定状态令牌的跨任务互斥锁,状态失效则获取失败:
var mutex = new StatefulMutex();
var state = mutex.State;
using (await mutex.AcquireAsync(state)) { }
mutex.InvalidateState();
using (await mutex.AcquireAsync(state)) { } // 抛出 InvalidOperationException
NotifyTaskCompletion<T>
任务包装器,完成时触发 PropertyChanged:
var watcher = new NotifyTaskCompletion<int>(LoadAsync());
watcher.PropertyChanged += (s, e) =>
{
if (e.PropertyName == nameof(watcher.IsFaulted) && watcher.IsFaulted)
Console.WriteLine(watcher.ErrorMessage);
};
AsyncContext 与 AsyncContextThread
AsyncContext.Run(async () =>
{
await Task.Delay(100);
// 此处 AsyncContext.Current != null
});
int result = AsyncContext.Run(async () =>
{
await Task.Delay(100);
return 42;
});
using (var thread = new AsyncContextThread())
{
await thread.Factory.Run(async () => await DoWorkAsync());
await thread.JoinAsync();
}
TimeoutValue / TimeoutTask
TimeoutValue timeout = TimeSpan.FromSeconds(5); // TimeSpan 隐式转换
timeout.InMilliseconds; // 5000
timeout.IsInfinite;
using (var t = new TimeoutTask(TimeSpan.FromSeconds(5), CancellationToken.None))
{
await t.Task; // 5 秒后完成
}
TaskHelper / TaskConstants / CancellationTokenTaskSource
Task done = TaskConstants.Completed; // 复用已完成实例
Task<int> zero = TaskConstants<int>.Default;
int result = TaskHelper.Run(async (int x) => new ValueTask<int>(x * 2), 21);
using (var source = new CancellationTokenTaskSource<int>(cts.Token))
{
Task<int> first = await Task.WhenAny(source.Task, DoWorkAsync());
if (first == source.Task) { /* 已取消 */ }
}
Nerosoft.Euonia.Threading.Interop
using Nerosoft.Euonia.Threading.Interop;
将回调 / 句柄等待转换为 Task:
public event EventHandler? MyEvent;
Task<EventArguments<object, EventArgs>> next =
EventAsyncFactory.FromEvent(h => MyEvent += h, h => MyEvent -= h);
MyEvent?.Invoke(this, EventArgs.Empty);
var args = await next;
var wh = new ManualResetEvent(false);
Task signalled = WaitHandleAsyncFactory.FromWaitHandle(wh);
wh.Set();
await signalledEDER;
释放(Nerosoft.Euonia.Disposing)
幂等的同步 / 异步释放原语。
同步
public sealed class Resource : SingleDisposable<FileStream>
{
public Resource(FileStream stream) : base(stream) { }
protected override void Dispose(FileStream context) => context.Dispose();
}
using (var r = new Resource(stream)) { }
// 委托释放
using (AnonymousDisposable.Create(() => Console.WriteLine("cleanup"))) { }
// 组合释放
using (var group = new CollectionDisposable(stream1, stream2))
{
group.Add(someExtraDisposable);
}
异步
public sealed class Resource : AsyncSingleDisposable<Stream>
{
public Resource(Stream stream) : base(stream) { }
protected override ValueTask DisposeAsync(Stream context) => context.DisposeAsync();
}
await using (var r = new Resource(stream)) { }
异常类型(System 命名空间)
所有异常均声明在 System 命名空间,抛出 / 捕获无需额外 using。
HTTP 状态异常
| 异常 | HTTP 状态码 |
|---|---|
BadRequestException |
400 |
ForbiddenException |
403 |
NotFoundException |
404 |
MethodNotAllowedException |
405 |
RequestTimeoutException |
408 |
ConflictException |
409 |
TooManyRequestsException |
429 |
UpgradeRequiredException |
426 |
InternalServerErrorException |
500 |
BadGatewayException |
502 |
ServiceUnavailableException |
503 |
GatewayTimeoutException |
504 |
throw new NotFoundException("订单 42 不存在。");
HttpStatusException
携带任意状态码的基异常:
throw new HttpStatusException(HttpStatusCode.Forbidden, "不能执行此操作");
HttpStatusCodeAttribute 与 ExceptionPrompt
var status = ex switch
{
HttpStatusException http => http.StatusCode,
_ => ex.GetType().GetCustomAttribute<HttpStatusCodeAttribute>()?.StatusCode
?? HttpStatusCode.InternalServerError
};
业务与通用异常
throw new NotFoundException("订单 42 不存在。"); // 404
throw new BusinessException("ORDER_OUT_OF_STOCK", "库存不足");
throw new ConfigurationException("缺失必要配置。");
throw new InvalidValueException("值无效。");
Nerosoft.Euonia.Security
using Nerosoft.Euonia.Security;
UserPrincipal
基于 ClaimsPrincipal 的只读类型化访问器:
var principal = new UserPrincipal(httpContext.User);
if (principal.IsAuthenticated && principal.IsInRole("Admin"))
{
string id = principal.UserId;
string name = principal.Username;
string tenant = principal.Tenant;
IEnumerable<string> roles = principal.Roles;
}
bool any = principal.IsInRoles("Admin,User", separator: ",");
var claim = principal.FindClaim("email");
UserClaimTypes
OIDC/JWT 声明名常量(Subject = "sub"、Name = "name"、Role = "role"、Tenant = "tenant" 等)。
账号与凭据异常
throw new AccountNotFoundException("user@example.com"); // 账号不存在
throw new AccountLockedException("user@example.com"); // 账号已锁定
throw new CredentialIncorrectException(userName); // 凭据不正确
catch (AccountException ex)
{
var identity = ex.Identity;
var details = ex.Details;
}
Nerosoft.Euonia.Windows
using Nerosoft.Euonia.Windows;
ICommand 实现,适用于 WPF / WinUI 等 MVVM 场景。
DelegateCommand / DelegateCommand<T>
var cmd = new DelegateCommand<string>(
s => Save(s),
s => !string.IsNullOrEmpty(s));
if (cmd.CanExecute(text)) { cmd.Execute(text); }
cmd.RaiseCanExecuteChanged();
GenericCommand / GenericCommand<T>
var cmd = new GenericCommand
{
CanExecuteCallback = p => p is int n && n > 0,
ExecuteCallback = p => Process((int)p!)
};
cmd.Execute(42);
System.ComponentModel.DataAnnotations 验证特性
GuidAttribute
校验字符串是否为合法 GUID:
public class OrderModel
{
[Required, Guid]
public string OrderId { get; set; }
}
CollectionCountAttribute
校验集合元素数量范围:
public class PagedModel
{
[CollectionCount(1, 100)] // 至少 1 个,至多 100 个
public ICollection<string> Tags { get; set; }
}
扩展方法(全局 Extensions)
库在全局命名空间提供了 Extensions 静态扩展类,按领域分文件组织:
// 字符串
string kebab = "HelloWorld".ToKebabCase(); // "hello-world"
string snake = "HelloWorld".ToSnakeCase(); // "hello_world"
string camel = "hello_world".ToCamelCase(); // "helloWorld"
bool isMail = "a@b.com".IsEmail(); // true
var trimmed = " text ".Trim(TextTrimType.Both);
// 集合
items.ForEach(x => Console.WriteLine(x));
var filtered = people.WhereIf(onlyAdults, p => p.Age >= 18);
var v = dict.GetValueOrDefault("k");
dict.GetOrAdd("k", () => new Value());
var sorted = deps.SortByDependencies(); // 拓扑排序
// 对象 / 反射
var session = obj.As<ISession>();
var to = obj.To<double>();
object city = Reflect.GetValue(person, typeof(Person), "Address.City");
// 异常 / 事件
string full = ex.GetFullMessage();
handler.CheckAndInvoke(this, e);
// 枚举
bool valid = someEnum.IsValid();
string desc = DayOfWeek.Monday.GetDescription();
// 线程 / Task
await someTask.WaitAsync(ct);
Task ignored = someTask.Ignore();
SynchronizationContextSwitcher.NoContext(() => { });
文档
更多详细信息与高级用法,参见 Euonia GitHub 仓库 上的官方文档。
注意事项 / 限制
- 大量类型位于全局命名空间或
System(Check、Optional<T>、ObjectId、Singleton<T>、Extensions等),与用户代码同名时需要用global::或全名限定,否则会解析到本库类型。 Singleton<T>.Instance在尚未赋值时直接读ConcurrentDictionary索引器,会抛KeyNotFoundException;请先Singleton<T>.Get(factory)或赋值(Source/Euonia.Core/System/Singleton.cs:12-24)。ObjectId.Snowflake()使用进程内单例SnowflakeId,而SnowflakeId是internal,machineId 与 datacenterId 固定为 0、外部无法配置(Source/Euonia.Core/System/SnowflakeId.cs:4);多进程/多机部署需要自行保证唯一性(例如改用ObjectId.Ulid()/ObjectId.Guid(GuidType)),否则同一毫秒内可能生成相同 ID。SnowflakeId.Next()在同一毫秒内自增序列号,序列耗尽时忙等下一毫秒;检测到时钟回拨会抛异常(IDS_TIMESTAMP_EARLIER_THAN_LAST),不会静默重试。AsyncLock/AsyncSemaphore等原语是进程内且不可重入的(Source/Euonia.Core/Threading/Coordination/AsyncLock.cs:10-12);跨进程互斥请使用Euonia.Concurrency系列包。- 本包没有 DI 注册入口(没有
AddCore):类型要么是静态工具,要么可直接new,直接调用即可,不要期待services.AddCore()。 - 目标框架为
net10.0/net11.0;更低 TFM 不在支持范围。
相关包
Euonia.Domain—— DDD 构建块(聚合根、值对象、领域事件、仓储契约)Euonia.Modularity—— 模块化启动与依赖注入Euonia.Mapping—— 对象映射抽象Euonia.Osba—— 业务对象运行时(基于本包的权限契约与反射工具)Euonia.Security—— 操作权限与行级数据权限策略引擎Euonia.Validation—— 参数与对象校验
常见问题与故障排查
多实例部署时 ObjectId.Snowflake() 生成重复 ID
原因:SnowflakeId 是 internal 单例,machineId 与 datacenterId 固定为 0(Source/Euonia.Core/System/SnowflakeId.cs:4),同一毫秒内两个进程会算出相同值(Source/Euonia.Core/System/ObjectId.cs:191)。
解决:分布式场景改用 ObjectId.Ulid() 或 ObjectId.Guid(GuidType);确实需要雪花 ID 时由宿主生成并保证机器位唯一,再 new ObjectId(long)。
读 Singleton<T>.Instance 抛 KeyNotFoundException
原因:Instance 的 getter 直接索引 ConcurrentDictionary,未初始化就抛异常(Source/Euonia.Core/System/Singleton.cs:12-16)。
解决:先 Singleton<T>.Get(() => new T()),或显式赋值 Singleton<T>.Instance = ...;需要随容器释放的对象不要放进 Singleton<T>。
异步锁偶发卡死
原因:AsyncLock 不可重入(Source/Euonia.Core/Threading/Coordination/AsyncLock.cs:10-12),同一异步流里嵌套 await _lock.LockAsync() 会等待自己已持有的锁。
解决:把加锁范围收敛到单个方法;跨方法时改用 AsyncMonitor,或给 LockAsync(ct) 传超时令牌。
业务代码里 Check / ObjectId 报 CS0104 二义性
原因:这些类型位于全局命名空间,与 using 引入的同名类型同时可见。
解决:用 global::Check / global::ObjectId 限定,或在文件顶部起别名;不要为此修改库的命名空间。
Check.Ensure 抛的是 InvalidOperationException
原因:Ensure 表示状态断言,失败抛 InvalidOperationException;只有 EnsureNotNull 抛 ArgumentNullException(Source/Euonia.Core/System/Check.cs:106-133)。
解决:参数校验用 EnsureNotNull / EnsureNotNullOrEmpty,业务前置条件用 Ensure,并在调用方 catch 对应类型。
最佳实践
- ID 选型跟着部署形态走:单进程用
ObjectId.Snowflake(),分布式默认ObjectId.Ulid(),需要与 Guid 生态互操作时用ObjectId.Guid(GuidType)。 - 锁只包住共享可变状态:
using (await _lock.LockAsync(ct))里不要放长耗时 I/O 或再次获取同一把锁。 - 异步原语一律传
CancellationToken:请求取消时等待能及时退出,避免线程与请求堆积。 - 进程级单例只放无状态工具:有生命周期的东西交给 DI 容器,不要塞进
Singleton<T>。 - 升级前读
## 版本与兼容:本包被所有 Euonia 包引用,TFM 或 BCL 行为变化会向下游扩散。
版本与兼容
| 项 | 值 |
|---|---|
| 目标框架 | net10.0、net11.0 |
| 包版本 | 2026.5.0(仓库根 project.props) |
| 第三方依赖 | 无(仅 BCL) |
- 文档标注的命名空间即当前源码位置(
Check/ObjectId/Extensions在全局,Optional<T>/Singleton<T>在System);升级后若发现位置变化,以源码为准并回提本文档。 SnowflakeId是internal,不在兼容性承诺内;外部只应依赖ObjectId的公开工厂方法。- 更低 TFM(
net8.0/net9.0)不在支持范围;跨大版本升级时先升 TFM,再升包。
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- No dependencies.
-
net11.0
- No dependencies.
NuGet packages (17)
Showing the top 5 NuGet packages that depend on Euonia.Core:
| Package | Downloads |
|---|---|
|
Euonia.Modularity
Euonia 模块化应用框架:可插拔模块、依赖图解析、约定式服务注册与应用生命周期管理。 / Modular application framework for Euonia: pluggable modules, dependency-graph resolution, convention-based service registration and application lifecycle management. |
|
|
Euonia.Domain
Euonia 领域驱动设计构建块:实体、聚合根、值对象、领域事件、命令与审计契约。 / Domain-Driven Design building blocks for Euonia: entities, aggregate roots, value objects, domain events, commands and auditing contracts. |
|
|
Euonia.Linq
Euonia LINQ 工具:规约模式、谓词与表达式构建器,以及过滤、分页和排序等查询扩展。 / LINQ utilities for Euonia: the specification pattern, predicate and expression builders, and queryable extensions for filtering, pagination and ordering. |
|
|
Euonia.Bus.RabbitMq
Euonia 总线 RabbitMQ 传输:分布式发布/订阅与请求-响应消息,支持持久连接、fanout 交换机、优先级队列、死信与 Polly 重试。 / RabbitMQ transport for Euonia Bus: distributed publish/subscribe and request-response messaging with persistent connections, fanout exchanges, priority queues, dead lettering and Polly-based retries. |
|
|
Euonia.Caching
Euonia 多级缓存框架:分层缓存句柄、缓存管理器编排、Backplane 同步与流式配置。 / Multi-level caching framework for Euonia: layered cache handles, cache-manager orchestration, backplane synchronization and fluent configuration. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 499 | 11/13/2026 |
| 2026.4.7 | 608 | 11/3/2026 |
| 2026.4.6 | 635 | 10/28/2026 |
| 2026.4.5 | 596 | 10/19/2026 |
| 2026.4.4 | 570 | 10/19/2026 |
| 2026.4.3 | 609 | 10/1/2026 |
| 2026.4.1 | 568 | 9/24/2026 |
| 2026.4.0 | 559 | 9/22/2026 |
| 2026.3.16 | 784 | 9/8/2026 |
| 2026.3.15 | 584 | 9/2/2026 |
| 2026.3.14 | 555 | 8/30/2026 |
| 2026.3.13 | 567 | 8/29/2026 |
| 2026.3.12 | 546 | 8/28/2026 |
| 2026.3.11 | 546 | 8/27/2026 |
| 2026.3.10 | 580 | 8/26/2026 |
| 2026.3.9 | 591 | 8/25/2026 |
| 2026.3.8 | 612 | 8/24/2026 |
| 2026.3.7 | 701 | 8/20/2026 |
| 2026.3.6 | 661 | 8/20/2026 |
| 2026.3.5 | 652 | 8/19/2026 |