Initial Commit ...

2024-01-25 04:48:33 +03:30
commit 9eabf45f06
15 changed files with 1299 additions and 0 deletions
@@ -0,0 +1,195 @@
+# xEventService
+
+it is a Part of xDashboard on SaherElm IT Center which provides: EventBus core and RabbitMQ implementation of if
+
+## Implementing
+
+for using the event bus, you had to create a classlib module and add a reference to this module inside it; then start to create your events.
+and for handling these events you had to add reference to this classlib in where you want to react to events, then create a class for handling this event which extends **IXEventHandler<>** interface.
+and finally subscribing to event handlers you want.
+
+## RabbitMQ
+
+for using RabbitMQ Eventbus you had to:
+
+- create it's configuration section in your **appSettings.json** file, like this:
+
+  ```javascript
+  {
+    ...
+    "EventServiceConfiguration": {
+    "Server": "YourRabbitMQHost",
+    "Port": rabbitMqPort,
+    "Username": "USERNAME",
+    "Password": "PASSWORD",
+    "AllowDynamicQueues": true
+    },
+    ...
+  }
+  ```
+
+**Note**: in configuration if you set **AllowDynamicQueues=false**, you had to provide all queue named and their configs manually.
+
+- register RabbitMQ implementation of IXEventBus in your **Startup**, like this:
+
+```c#
+
+...
+public void ConfigureServices (IServiceCollection services) {
+    ...
+    //
+    // Register RabbitMQ Event Service ...
+    services.AddXEventService (Configuration);
+    ...
+}
+...
+```
+
+## Events
+
+for each Event you need to implement 3 classes:
+
+- a DTO class for provide required properties for creating Event Object instance; all properties in this class is public.
+
+  > this used when you want to get som information from another sources, such as [FromBody] in Controller Actions.
+
+- one class which carry required data for Event object; this class must extends from **XEvent** class and must contains all Dto class properties in { get; protected set; } style;
+
+- one or more class which provide Event arrounds the Event object whith propper constructor to Create it's instance;
+
+for better undrestanding please follow this structure:
+
+```c#
+
+public class XPersonEventDto {
+    public string Firstname { get; set; }
+    public string Lastname { get; set; }
+}
+
+public class XPersonEvent : XEvent {
+    public string Firstname { get; protected set; }
+    public string Lastname { get; protected set; }
+}
+
+public class XCreatePersonEvent : XPersonEvent {
+    public XCreatePersonEvent (
+        string firstname,
+        string lastname
+    ) {
+        Firstname = firstname;
+        Lastname = lastname;
+    }
+}
+
+public class XPersonCreatedEvent : XPersonEvent {
+    public Guid Id { get; protected set; }
+
+    public XPersonCreatedEvent (
+        Guid id,
+        string firstname,
+        string lastname
+    ) {
+        Id = id;
+        Firstname = firstname;
+        Lastname = lastname;
+    }
+}
+```
+
+## EventHandlers
+
+in where you want to handle this events and react to them, for each event you had to create an event handler class.
+
+```c#
+
+public class XCreatePersonEventHandler : IXEventHandler<XCreatePersonEvent> {
+    private readonly IXEventBus eventBus;
+    private ILogger<XCreatePersonEventHandler> logger;
+
+    public XCreatePersonEventHandler (
+        IXEventBus eventBus,
+        ILoggerFactory loggerFactory
+    ) {
+        this.logger = loggerFactory.CreateLogger<XCreatePersonEventHandler> ();
+        this.eventBus = eventBus;
+    }
+
+    public async Task HandleAsync (XCreatePersonEvent @event) {
+        //
+        logger.LogInformation ($"Received Event: {@event.ToJSON()}");
+
+        //
+        // Publish XPersonCreated Event ...
+        var personCreatedEvent = new XPersonCreatedEvent (
+            id: Guid.NewGuid (),
+            firstname: @event.Firstname,
+            lastname: @event.Lastname
+        );
+
+        //
+        eventBus.Publish (personCreatedEvent);
+
+        //
+        await Task.CompletedTask;
+    }
+}
+
+public class XPersonCreatedEventHandler : IXEventHandler<XPersonCreatedEvent> {
+    private ILogger<XPersonCreatedEventHandler> logger;
+
+    public XPersonCreatedEventHandler (ILoggerFactory loggerFactory) {
+        this.logger = loggerFactory.CreateLogger<XPersonCreatedEventHandler> ();
+    }
+
+    public async Task HandleAsync (XPersonCreatedEvent @event) {
+        //
+        logger.LogInformation ($"Received Event: {@event.ToJSON()}");
+        await Task.CompletedTask;
+    }
+}
+```
+
+and register your event handlers in **Startup**, like this:
+
+```c#
+
+...
+public void ConfigureServices (IServiceCollection services) {
+    ...
+    //
+    // Register Event Handlers ...
+    services.AddXEventHandler<XCreatePersonEvent, XCreatePersonEventHandler> ();
+    services.AddXEventHandler<XPersonCreatedEvent, XPersonCreatedEventHandler> ();
+
+    //
+    // Register Event Service ...
+    services.AddXEventService (Configuration);
+    ...
+}
+...
+```
+
+## Subscribe
+
+for each event you had to respond in yor project, after create related EventHandler, last step is subscribing to the event in IXEventBus implementation in **Startup**, like this:
+
+```c#
+
+...
+public void Configure (IApplicationBuilder app, IWebHostEnvironment env) {
+    ...
+    //
+    // Subscribe to Events ...
+    app.XEventSubscribe<XCreatePersonEvent, XCreatePersonEventHandler> ();
+    app.XEventSubscribe<XPersonCreatedEvent, XPersonCreatedEventHandler> ();
+    ...
+}
+```
+
+## Maintainer
+
+Hadi Khazaee asl
+
+[https://www.saherelm.ir](https://www.saherelm.ir)
+
+[hadi_khazaee_asl@yahoo.com](mailto:hadi_khazaee_asl@yahoo.com)