Netor.EventHub.SourceGenerator 1.1.0

Netor.EventHub.SourceGenerator

项目概述

Netor.EventHub.SourceGenerator 是 Netor.EventHub 的增量源代码生成器（Incremental Source Generator）。

它在编译期自动扫描程序集中所有继承自 EventID<T> 的类型，为 ISubscriber 生成强类型的 On 扩展方法，为 IPublisher 生成强类型的 Emit/EmitAsync 扩展方法，省去手动编写样板代码。

工作原理

输入

定义一个继承自 EventID<T> 的事件标识类型：

using Netor.EventHub;

// 自定义事件参数
public record ChatMessageArgs : IEventArgs
{
    public string ID { get; set; } = Guid.NewGuid().ToString("N");
    public string From { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
}

// 自定义事件标识（继承 EventID<T>）
public record ChatMessageEventID() : EventID<ChatMessageArgs>("chat.message");

输出

生成器在编译期自动生成以下扩展方法：

// <auto-generated/>
namespace Netor.EventHub;

public static partial class ISubscriberExtensions
{
    extension(ISubscriber subscriber)
    {
        /// <summary>
        /// 订阅 <see cref="ChatMessageEventID"/> 事件。
        /// </summary>
        public Guid On(ChatMessageEventID eventid, EventHandler<ChatMessageArgs> handler)
        {
            return subscriber.Subscribe(eventid, handler);
        }
    }
}

使用生成的方法

var subscriber = serviceProvider.GetRequiredService<ISubscriber>();

// 直接使用强类型的 On 方法，无需手动指定泛型参数
subscriber.On(new ChatMessageEventID(), async (context, args) =>
{
    Console.WriteLine($"收到来自 {args.From} 的消息: {args.Content}");
    return false;
});

IPublisher 扩展（v1.1.0 新增）

生成器同时为 IPublisher 生成 Emit 和 EmitAsync 扩展方法：

// <auto-generated/>
namespace Netor.EventHub;

public static partial class IPublisherExtensions
{
    extension(IPublisher publisher)
    {
        /// <summary>
        /// 发布 <see cref="ChatMessageEventID"/> 事件。
        /// </summary>
        public void Emit(ChatMessageEventID eventid, ChatMessageArgs payload, CancellationToken cancellationToken = default)
        {
            publisher.Publish(eventid, payload, cancellationToken);
        }

        /// <summary>
        /// 异步发布 <see cref="ChatMessageEventID"/> 事件。
        /// </summary>
        public Task EmitAsync(ChatMessageEventID eventid, ChatMessageArgs payload, CancellationToken cancellationToken = default)
        {
            return publisher.PublishAsync(eventid, payload, cancellationToken);
        }
    }
}

使用生成的发布方法

var publisher = serviceProvider.GetRequiredService<IPublisher>();

// 同步发布，无需手动指定泛型参数
publisher.Emit(new ChatMessageEventID(), new ChatMessageArgs
{
    From = "Alice",
    Content = "Hello!"
});

// 异步发布
await publisher.EmitAsync(new ChatMessageEventID(), new ChatMessageArgs
{
    From = "Bob",
    Content = "Hi there!"
});

安装

此生成器已随 Netor.EventHub NuGet 包自动引用，无需单独安装。

如需独立使用，可手动添加引用：

<ItemGroup>
  <ProjectReference Include="path\to\Netor.EventHub.Generator.csproj"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

查看生成的代码

在项目文件中添加以下属性，即可在 obj 目录下查看生成的源码：

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

生成的文件位于：

obj/Debug/{tfm}/generated/Netor.EventHub.Generator/
    Netor.EventHub.Generator.SubscriberExtensionGenerator/
        ISubscriberExtensions.g.cs
        IPublisherExtensions.g.cs

注意事项

• 生成器仅处理当前编译中定义的 EventID<T> 子类型，不会重复生成引用程序集中的类型。
• 所有类型引用均使用 global:: 完全限定名，确保跨命名空间正确解析。
• 需要 C# 14 或更高版本（extension 成员语法）。
• Emit/EmitAsync 方法透传 CancellationToken，默认值为 default。