xEventService/README.md

# 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)