Eventhandler toolbox
To add the toolbox to a project, you add the package to the project.json :
"dependencies": {
"Digipolis.Toolbox.Eventhandler": "1.0.1"
}
In Visual Studio you can also use the NuGet Package Manager to do this.
The Event toolbox is registered in the ConfigureServices method of the Startup class.
There are 2 ways to configure the Event toolbox :
- using a json config file
- using code
The path to the Json config file has to be given as argument to the AddEventHandler method :
services.AddEventHandler(opt => opt.FileName = ConfigPath + "/eventhandlerconfig.json");
The Event toolbox will read the given section of the json file with the following structure :
{
"EventHandler": {
"Version": "1",
"MessageVersion": "1",
"AppId": "666",
"AppName": "SampleApi",
"InstanceId": "123",
"InstanceName": "MySampleInstance",
"EventEndpointUrl": "https://myendpoint.com",
"EventEndpointNamespace": "EventNamespace",
"EventEndpointApikey": "6546-6544-6464-6654",
"EventEndpointOwnerkey": "dgpls",
"HideEventHandlerErrors": true
}
}
You can also call the AddEventHandler method, passing in the needed options directly :
services.AddDataAccess<MyEntityContext>(opt => opt.Version = 1, (...) );
public static IServiceCollection AddBusinessServices(this IServiceCollection services)
{
// Register your business services here, e.g. services.AddTransient<IMyService, MyService>();
services.AddTransient<IEventHandler, EventHandler>();
return services;
}
This toolbox was made to be able to send events from ASP.NET Core applications. This allows the developers to send out events in a quick and uniform way.
The event message has the following structure :
Header | ||
Timestamp | 2012-01-01T12:00:00Z | Timestamp of the event. |
Version | 1 | Version of the event handler. |
Correlation | ||
CorrelationId | 8e82e349-b430-4c7b-a86a-b8b6133382e9 | Unique id of the request. |
Application | ||
ApplicationId | b02ea486-506a-47e4-b136-cd658eb8f805 | Unique id of the application that initiated the request. |
ApplicationName | MyUserInterface | Display-name of the application that initiated the request. |
Instance | ||
InstanceId | 24213d47-1c26-46d5-a0d1-52d9c3913935 | Unique id of the instance of the application that initiated the request. |
InstanceName | MyUserInterface-instance3 | Display-name of the instance of the application that initiated the request. |
Source | ||
Application | ||
ApplicationId | 1df240eb-7d0e-42c0-9bb3-f22ad30fd353 | Unique id of the application that publishes the event. |
ApplicationName | myApp | Display-name of the application that publishes the event. |
Instance | ||
InstanceId | e75ab07e-e96c-462c-962c-393ecfdc5726 | Unique id of the instance of the application that publishes the event. |
InstanceName | myApp-instance1 | Display-name of the instance of the application that publishes the event. |
Component | ||
ComponentId | 9da00df0-6bb3-4b22-be90-3f3bc70329ad | Unique id of the component in the application that publishes the event. |
ComponentName | Invoicer | Display-name of the components in the application that publishes the event. |
Host | ||
IPAddress | 126.35.45.2 | IP adress of the server where the event is being published. |
ProcessId | 15984 | Process id from where the event is being sent. |
ThreadId | 6875 | Thread id from where the event is being sent. |
Body | ||
EventVersion | 1 | Version of the event (can be used by parsers). |
User | ||
UserName | theuser | User that sends the event. |
IPAddress | 168.237.25.91 | IP adress of that user. |
Event | ||
Type | invoice:created | Type of the event. |
Content | {"id":45987} | Content of the event (can be empty if the event type speaks for itself). |
Format | json | Format of the content (can be used by parsers). |
The Header contains the metadata, the Body the real message.
The display-friendly names are a tool for the subscribers of the events. Id’s alone are usually not very user-friendly. By using the display-friendly names subscribes can get the name right away.
The version fields can be used when logic needs to be executed on the messages (eg by parsers or (de)serializers). Between versions the structure or content could have changed.
The toolbox offers methods to send out events in a user-friendly manner. The metadata fields are filled in by the toolbox.
(Refer to the samples project to see a working demo)
-
Publish(topic, eventtype, [principal], componentId, componentname, optional eventFormat)
The toolbox will serialize the datatype to JSON and send it as content.
-
PublishString(topic, eventtype, string, componentId, componentname, optional eventFormat)
The toolbox will convert the string to a json with 1 field and send it as content.
-
PublishJson(topic, eventtype, json-string, componentId, componentname, optional eventFormat)
The toolbox will pass the json-string literally as content.
For event types the following format is recommended : entity:operation (eg person:changed, invoice:created, payment:recieved)