Euonia.Core 2026.5.0

dotnet add package Euonia.Core --version 2026.5.0
                    
NuGet\Install-Package Euonia.Core -Version 2026.5.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Euonia.Core" Version="2026.5.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Euonia.Core" Version="2026.5.0" />
                    
Directory.Packages.props
<PackageReference Include="Euonia.Core" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Euonia.Core --version 2026.5.0
                    
#r "nuget: Euonia.Core, 2026.5.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Euonia.Core@2026.5.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Euonia.Core&version=2026.5.0
                    
Install as a Cake Addin
#tool nuget:?package=Euonia.Core&version=2026.5.0
                    
Install as a Cake Tool

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 不在支持范围。

相关包

常见问题与故障排查

多实例部署时 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • 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
Loading failed