Events

EventAggregator 双端

命名空间 Events

public class EventAggregator : IDisposable

基于弱引用的事件聚合器，订阅者通过 WeakReference1` 持有以避免内存泄漏。 已释放的订阅者会在下次发布时自动清理。

构造函数

EventAggregator 双端

public EventAggregator()

属性

CaptureCallerStackTrace 双端

public static bool CaptureCallerStackTrace { get; set; }

Determines whether the caller's stack trace should be captured when publishing events. If enabled, a StackTrace will be created and passed to the event exception handlers. This can be useful for debugging or logging purposes but may have a performance impact, as the stack trace will be captured for every event published even if no exceptions occur. Default value is false.

Logger 双端

public static ILogger? Logger { get; set; }

方法

Subscribe 双端

public virtual void Subscribe<TEvent>(WeakReference<ITrigger> wrTrigger)

Unsubscribe 双端

public virtual void Unsubscribe<TEvent>(WeakReference<ITrigger> wrTrigger)

ForgetRun 双端

public static void ForgetRun(Task task, StackTrace? callerStackTrace)

Destroy 双端

public void Destroy()

Dispose 双端

protected virtual void Dispose(bool disposing)

事件

TaskUnhandledException 双端

public static event TaskUnhandledExceptionEventHandler? TaskUnhandledException

字段

eventSubscribers 双端

protected TypeMap<List<WeakReference<ITrigger>>> eventSubscribers

disposedValue 双端

protected bool disposedValue

IEventSender 双端

命名空间 Events

public interface IEventSender

属性

Aggregator 双端

public EventAggregator Aggregator { get; }

AggregatorWeakReference 双端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

方法

Publish 双端

void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 双端

Action<TEvent>? GetPublisher<TEvent>()

IEventSenderExtensions 双端

命名空间 Events

public static class IEventSenderExtensions

方法

Publish 双端

public static void Publish<TEvent>(this IEventSender sender, TEvent eventToPublish)

GetPublisher 双端

public static Action<TEvent>? GetPublisher<TEvent>(this IEventSender sender)

Subscribe 双端

public static Trigger<TEvent> Subscribe<TEvent>(this IEventSender sender, TriggerEventHandle<TEvent> handler, bool keepReference = true) where TEvent : class, ITriggerEvent<TEvent>

创建并注册一个触发器，用于订阅指定类型的事件。

• sender — 事件发送者，触发器将注册到此对象
• handler — 事件处理器委托，当事件触发时将调用此委托
• keepReference — 是否保持对触发器的硬引用以防止被垃圾回收，默认为 true

返回： 创建的触发器对象，可用于后续控制（如销毁、禁用等）

备注

此方法是创建和注册触发器的便捷方法，相当于以下代码的简化版本： var trigger = new Trigger<TEvent>(handler, keepReference); trigger.Register(sender); 使用场景： 快速订阅事件，无需手动创建和注册触发器 适用于大多数简单的事件监听场景 避免忘记注册触发器的问题 示例： // 订阅对话完成事件 var trigger = Game.Instance.Subscribe<EventConversationCompleted>(async (sender, e) => { Game.Logger.LogInfo("对话完成: {0}", e.Conversation.Cache.Link.FriendlyName); return true; }); // 需要时可以销毁触发器 trigger.Destroy();

Subscribe 双端

public static Trigger<TEvent> Subscribe<TEvent>(this IEventSender sender, Func<object, TEvent, Task> handler, bool keepReference = true) where TEvent : class, ITriggerEvent<TEvent>

创建并注册一个触发器（简化版，无需返回布尔值）。

• sender — 事件发送者，触发器将注册到此对象
• handler — 事件处理器委托，当事件触发时将调用此委托
• keepReference — 是否保持对触发器的硬引用以防止被垃圾回收，默认为 true

返回： 创建的触发器对象，可用于后续控制（如销毁、禁用等）

ITrigger 双端

命名空间 Events

public interface ITrigger

定义事件触发器的基本接口，用于响应和处理事件系统中的特定事件。 触发器通过弱引用机制管理事件订阅，支持自动垃圾回收和生命周期管理。

备注

触发器是事件系统的核心组件，它们： 订阅来自 IEventSender 的特定事件 在事件发生时异步执行处理逻辑 使用弱引用避免内存泄漏 支持硬引用集合防止意外的垃圾回收

属性

IsValid 双端

public bool IsValid { get; }

获取触发器是否处于有效状态。

备注

当触发器被销毁（调用 Destroy 方法）后，此属性将返回 false。 无效的触发器不会处理任何事件。

IsEnabled 双端

public bool IsEnabled { get; set; }

获取或设置触发器是否启用。

备注

禁用的触发器仍然保持与事件发送者的订阅关系，但不会执行事件处理逻辑。 这提供了一种临时暂停触发器而不需要完全注销的机制。

HardReferences 双端

protected static HashSet<ITrigger> HardReferences { get; }

硬引用集合，用于防止触发器被垃圾回收。

备注

当创建触发器时指定 keepReference 参数为 true，或者需要确保触发器不被意外回收时， 触发器会被添加到此集合中。使用完毕后应调用 Destroy 方法从集合中移除。

方法

Execute 双端

Task<bool> Execute<TEventCaller>(object sender, TEventCaller eventArgs)

异步执行触发器的事件处理逻辑。

• sender — 触发事件的发送者对象
• eventArgs — 事件参数，包含事件的具体数据

返回： 返回一个 Task1，其结果表示事件是否被成功处理： true- 事件处理成功false` - 事件处理失败或事件类型不匹配

AddEvent 双端

void AddEvent<TEventCaller>(IEventSender sender)

向指定的事件发送者注册此触发器，开始监听特定类型的事件。

• sender — 事件发送者，触发器将订阅其 EventAggregator

备注

此方法已过时，建议使用具体实现类中的 Register 方法。 注册后，当发送者发布指定类型的事件时，此触发器的 Object,``0) 方法将被调用。

RemoveEvent 双端

void RemoveEvent<TEventCaller>(IEventSender sender)

从指定的事件发送者注销此触发器，停止监听特定类型的事件。

• sender — 事件发送者，触发器将从其 EventAggregator 中注销

备注

此方法已过时，建议使用具体实现类中的 Unregister 方法。 注销后，此触发器将不再接收来自该发送者的指定类型事件。

Destroy 双端

void Destroy()

销毁触发器，释放所有资源并从事件系统中完全移除。

备注

此方法将： 从所有已注册的事件发送者中注销触发器 从硬引用集合中移除触发器 清理内部资源和引用 将 IsValid 设置为 false

Events 双端

IEnumerable<(EventAggregator sender, Type eventType)> Events()

获取当前触发器订阅的所有事件发送者和事件类型的集合。

返回： 返回一个包含元组的枚举，每个元组包含： sender - 事件聚合器 EventAggregator eventType - 订阅的事件类型 Type

备注

此方法主要用于调试和监控触发器的订阅状态。 返回的集合只包含仍然有效的（未被垃圾回收的）事件聚合器。

EventsGC 双端

void EventsGC()

执行垃圾回收，清理已失效的弱引用。

备注

此方法会遍历内部存储的弱引用集合，移除那些目标对象已被垃圾回收的弱引用。 定期调用此方法有助于保持触发器的内存效率，防止弱引用集合无限增长。

ITriggerEvent 双端

命名空间 Events

public interface ITriggerEvent<TSelf> where TSelf : class, ITriggerEvent<TSelf>

ITriggerEventToken 双端

命名空间 Events

public interface ITriggerEventToken<TEvent> where TEvent : class, ITriggerEvent<TEvent>

Trigger 双端

命名空间 Events

public class Trigger<TEvent> : ITrigger, IDisposable where TEvent : class, ITriggerEvent<TEvent>

泛型触发器实现，专门处理单一类型的事件，提供高性能的事件处理能力。

备注

Trigger1是针对单一事件类型优化的触发器实现，具有以下特点： 高性能：由于只处理一种事件类型，避免了类型检查和转换的开销 类型安全：编译时确保事件类型的正确性 弱引用管理：自动管理与事件聚合器的弱引用关系 生命周期控制：支持显式的资源释放和垃圾回收 与TriggerDynamic` 相比，此类在性能上更优，但灵活性较低，只能处理指定的单一事件类型。

构造函数

Trigger 双端

public Trigger(TriggerEventHandle<TEvent> action, bool keepReference = true)

初始化 Trigger1` 类的新实例。

• action — 事件处理器委托，当事件被触发时将调用此委托。 委托应返回 true 表示事件处理成功，false 表示处理失败。
• keepReference — 是否在 HardReferences 集合中保持对此触发器的硬引用， 防止其被垃圾回收。默认为 false。

备注

创建触发器后，需要调用 IEventSender) 方法将其注册到相应的事件发送者， 才能开始接收和处理事件。 如果 为 true，触发器将不会被垃圾回收， 直到显式调用 Destroy 方法。这在某些长生命周期的场景中很有用。

Trigger 双端

public Trigger(Func<object, TEvent, Task> action, bool keepReference = true)

初始化 Trigger1` 类的新实例（简化版，无需返回布尔值）。

• action — 事件处理器委托，当事件被触发时将调用此委托。
• keepReference — 是否在 HardReferences 集合中保持对此触发器的硬引用， 防止其被垃圾回收。默认为 true。

属性

IsValid 双端

public bool IsValid { get; }

获取触发器是否处于有效状态。

IsEnabled 双端

public bool IsEnabled { get; set; }

获取或设置触发器是否启用。

方法

Execute 双端

public Task<bool> Execute(object sender, TEvent eventArgs)

执行事件处理逻辑的强类型版本。

• sender — 触发事件的发送者对象
• eventArgs — 类型为 的事件参数

返回： 返回一个 Task1，表示触发器处理的结果： true- 触发器处理成功（通过条件判定）false` - 触发器条件判定失败或触发器被禁用

备注

此方法是 Object,``0) 的强类型版本， 只有当触发器启用（IsEnabled 为 true）时才会执行处理逻辑。

Destroy 双端

public void Destroy()

销毁触发器，释放所有资源。这是 Dispose 的公共包装器。

Events 双端

public IEnumerable<(EventAggregator sender, Type eventType)> Events()

获取当前触发器订阅的事件聚合器和事件类型信息。

返回： 返回包含有效事件聚合器和事件类型的元组集合。 每个元组包含 EventAggregator 实例和 类型。

EventsGC 双端

public void EventsGC()

清理失效的弱引用，释放不再有效的事件聚合器引用。

Dispose 双端

protected virtual void Dispose(bool disposing)

释放触发器使用的托管和非托管资源。

• disposing — true 表示从 Dispose 调用； false 表示从终结器调用。

AddEvent 双端

public void AddEvent(IEventSender sender)

Register 双端

public void Register(IEventSender sender)

将触发器注册到指定的事件发送者，开始监听事件。

• sender — 事件发送者，触发器将订阅其 EventAggregator 来接收 类型的事件。

备注

注册后，当发送者发布 类型的事件时， 此触发器的 Object,0)` 方法将被异步调用。 可以多次调用此方法将触发器注册到多个事件发送者。 触发器使用弱引用来避免阻止事件发送者被垃圾回收。

RemoveEvent 双端

public void RemoveEvent(IEventSender sender)

Unregister 双端

public void Unregister(IEventSender sender)

从指定的事件发送者注销触发器，停止监听事件。

• sender — 要注销的事件发送者，触发器将从其 EventAggregator 中移除订阅。

备注

注销后，此触发器将不再接收来自该发送者的 类型事件。 如果触发器未注册到此发送者，调用此方法不会产生任何效果。

ToString 双端

public override string ToString()

返回表示当前触发器状态的字符串表示形式。

返回： 包含触发器关键状态信息的字符串，包括事件类型、启用状态、有效性和订阅数量。

备注

此方法主要用于调试和日志记录，提供触发器的快速状态概览。 返回格式：Trigger<EventType>[Status, Subscriptions: count, InHardReferences: bool]

TriggerCompatibilityExtensions 双端

命名空间 Events

public static class TriggerCompatibilityExtensions

Compatibility shims for trigger-editor generated code.

方法

AddEvent 双端

public static void AddEvent<TEvent>(this Trigger<TEvent> trigger, IEventSender sender) where TEvent : class, ITriggerEvent<TEvent>

Temporary workaround for trigger-editor generated AddEvent<TEvent> calls on Trigger<TEvent>.

TriggerDynamic 双端

命名空间 Events

public class TriggerDynamic : ITrigger, IDisposable

动态触发器实现，支持处理多种不同类型的事件，但相比单一事件触发器有一定的性能开销。

备注

TriggerDynamic 适用于需要处理多种事件类型的场景，具有以下特点： 多事件支持：可以同时订阅和处理多种不同类型的事件 运行时灵活性：可以在运行时动态添加或移除不同类型的事件订阅 性能开销：由于需要支持动态类型，存在一定的性能损耗 类型擦除：使用 dynamic 类型处理事件参数 如果只需要处理单一类型的事件，建议使用 Trigger1` 以获得更好的性能。

构造函数

TriggerDynamic 双端

public TriggerDynamic(TriggerEventHandle<dynamic> action, bool keepReference = true)

初始化 TriggerDynamic 类的新实例。

• action — 动态事件处理器委托，接受 dynamic 类型的事件参数。 委托应返回 true 表示事件处理成功，false 表示处理失败。
• keepReference — 是否在 HardReferences 集合中保持对此触发器的硬引用， 防止其被垃圾回收。默认为 true。

备注

创建动态触发器后，需要使用 IEventSender) 方法 为每种要处理的事件类型进行注册。

TriggerDynamic 双端

public TriggerDynamic(Func<object, dynamic, Task> action, bool keepReference = true)

初始化 TriggerDynamic 类的新实例（简化版，无需返回布尔值）。

• action — 动态事件处理器委托，接受 dynamic 类型的事件参数。
• keepReference — 是否在 HardReferences 集合中保持对此触发器的硬引用， 防止其被垃圾回收。默认为 true。

属性

IsEnabled 双端

public bool IsEnabled { get; set; }

获取或设置触发器是否启用。

IsValid 双端

public bool IsValid { get; }

获取触发器是否处于有效状态。

方法

Execute 双端

public Task<bool> Execute<TEventCaller>(object sender, TEventCaller eventArgs)

执行事件处理逻辑，支持任意类型的事件参数。

• sender — 触发事件的发送者对象
• eventArgs — 事件参数

返回： 返回一个 Task1`，表示事件处理的结果。 如果 为 null，则返回 false。

Destroy 双端

public void Destroy()

销毁触发器，释放所有资源。这是 Dispose 的公共包装器。

Dispose 双端

protected virtual void Dispose(bool disposing)

释放触发器使用的托管和非托管资源。

• disposing — true 表示从 Dispose 调用； false 表示从终结器调用。

AddEvent 双端

public void AddEvent<TEventCaller>(IEventSender sender)

向指定的事件发送者注册此触发器，开始监听特定类型的事件。

• sender — 事件发送者，触发器将订阅其 EventAggregator 来接收指定类型的事件。

备注

可以多次调用此方法为不同的事件类型进行注册。 每种事件类型都会被单独管理，互不影响。

RemoveEvent 双端

public void RemoveEvent<TEventCaller>(IEventSender sender)

从指定的事件发送者注销此触发器，停止监听特定类型的事件。

• sender — 事件发送者，触发器将从其 EventAggregator 中注销指定类型的事件订阅。

备注

注销后，此触发器将不再接收来自该发送者的指定类型事件。 如果该事件类型的所有订阅都被移除，相关的内部数据结构也会被清理。

Events 双端

public IEnumerable<(EventAggregator sender, Type eventType)> Events()

获取当前触发器订阅的所有事件聚合器和事件类型信息。

返回： 返回包含有效事件聚合器和对应事件类型的元组集合。

EventsGC 双端

public void EventsGC()

清理失效的弱引用，释放不再有效的事件聚合器引用。

备注

此方法会遍历所有事件类型的聚合器集合，移除失效的弱引用。 如果某个事件类型的聚合器集合变为空，该事件类型的记录也会被完全移除。

字段

weakReference 双端

public WeakReference<ITrigger> weakReference

触发器的弱引用，用于在事件聚合器中进行订阅管理。

TriggerEventHandle 双端

命名空间 Events

public delegate TriggerEventHandle<TEvent>