Brainix.GoalsCommon 1.0.0-beta-112

This is a prerelease version of Brainix.GoalsCommon.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Brainix.GoalsCommon --version 1.0.0-beta-112
                    
NuGet\Install-Package Brainix.GoalsCommon -Version 1.0.0-beta-112
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Brainix.GoalsCommon" Version="1.0.0-beta-112" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Brainix.GoalsCommon" Version="1.0.0-beta-112" />
                    
Directory.Packages.props
<PackageReference Include="Brainix.GoalsCommon" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Brainix.GoalsCommon --version 1.0.0-beta-112
                    
#r "nuget: Brainix.GoalsCommon, 1.0.0-beta-112"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Brainix.GoalsCommon@1.0.0-beta-112
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Brainix.GoalsCommon&version=1.0.0-beta-112&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Brainix.GoalsCommon&version=1.0.0-beta-112&prerelease
                    
Install as a Cake Tool

Documentation

Summary

The GoalsCommon Package is a package that consists of three main parts: a RabbitMQ bus, the learning tree structure and a DataLoad helper.

Dependencies

The GoalsCommon Package has the following dependencies:

Usage

Installation

To install the GoalsCommon Package, the following command must be executed in the project's folder:

dotnet add package Brainix.GoalsCommon --prerelease

Initialization of the RabbitMQ bus

The RabbitMQ bus is to be controlled via the Brainix.GoalsCommon.RabbitMQ.Bus.IBrainixEventBus interface. There are two implementations for this in the Goals-Common package. The Brainix.GoalsCommon.RabbitMQ.Bus.DefaultRabbitMQBus class is used for normal communication with a RabbitMQ server. The Brainix.GoalsCommon.RabbitMQ.Bus.TestRabbitMQBus class was written to efficiently create integration tests with RabbitMQ.

DefaultRabbitMQBus

The DefaultRabbitMQBus is initialised with a RabbitMQConfiguration. This contains the complete ConnectionString and an ApplicationName. A normal initialisation would look like this:

using Brainix.GoalsCommon.RabbitMQ.Bus;
...
var brainixEventBus = new DefaultRabbitMQBus(new RabbitMQConfiguration(
	"amqp://username:password@url:port/",
	"serviceName"
));

In a real use case, the values for the ConnectionString and the ApplicationName would of course have to be chosen appropriately. A classic initialisation in the context of a dependency injection would look like this:

using Brainix.GoalsCommon.RabbitMQ.Bus;
...
services.AddSingleton<IBrainixEventBus, DefaultRabbitMQBus>(conf => new DefaultRabbitMQBus(
	new RabbitMQConfiguration(
		Configuration.GetConnectionString("rabbit_mq").Replace(<%password%>",vault.rabbitMQPassword),
		"TrainingCenter"
	)
));
TestRabbitMQBus

The TestRabbitMQBus is only initialised with a messageDelayInMs. The number of milliseconds by which the transmission of a new message to the consumer should be delayed is passed here. A classic initialisation in the context of a dependency injection would look as follows:

using Brainix.GoalsCommon.RabbitMQ.Bus;
...
services.AddSingleton<IBrainixEventBus, TestRabbitMQBus>((messageDelayInMs) => new TestRabbitMQBus(1));

BrainixEvents

All events that should be processed by the RabbitMQ bus must inherit from the generic, abstract class Brainix.GoalsCommon.RabbitMQ.Models.BrainixEvent. Each event shall contain a clearly defined data structure. The purpose of each event shall be explained in a short DocString. Each BrainixEvent also has the possibility to declare different event types. This can be done by declaring a public, internal enum with the name EventType for the respective BrainixEvent (Here it is very important that the name of the enum is written exactly like this). Here is a short example:

using System;

namespace Brainix.GoalsCommon.RabbitMQ.Models.DomainEvents
{
	/// <summary>
	///	This event is used for publishing Notifications that were produced by a specific user.
	/// </summary>
	public class NotificationEvent: BrainixEvent
	{
		public Guid SenderUserId { get; set; }
		public string NotificationContent { get; set; }
		public enum EventType
		{
			Information,
			Warning
		}
	}
}

Routing logic for BrainixEvents

The routing logic in RabbitMQ EventBus is based on topic exchanges and work queues. The underlying idea is that each event is published via its own exchange. Each individual microservice that wants to consume this event has its own queue that is bound to the respective exchange via one or more binding keys. The individual instances of the microservice consume directly from the queue. In concrete terms, this means that when a new Brainix event is published, an exchange with the name of the event is created. If a microservice specifies that it consumes an event, a queue is created and bound to the exchange. Here, all events - regardless of type - are consumed initially. If the consumer specifies that only a certain event types should be consumed, the binding key (between the exchange and the queue) will carry the names of the event types. From now on, only events of that types will be placed in the respective queue. This logic is illustrated by the following diagram: Diagram

Publish

To send an event, the method Publish<T>(T brainixEvent, Func<BrainixEventCallback, Task> callbackDelegate) where T : BrainixEvent must be called from the Brainix.GoalsCommon.RabbitMQ.Bus.IBrainixEventBus. This will take the event to be sent and optionally a callback function which will be called once the event has been successfully sent to the RabbitMQServer and the reception has been confirmed. By default, an event is initialised with the Default event type, where the EventTypeNumber has the value 0. If a special EventType should be set, then the EventTypeNumber property must be filled with the number of the matching element of the respective EventType enumeration. Here is a short example:

brainixEventBus.Publish(new NotificationEvent
{
	EventTypeNumber = (int) NotificationEvent.EventType.Information,
	SenderUserId = new Guid("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
    NotificationContent = "Hello World!"
}, async (brainixEventCallback) =>
{
    if(brainixEventCallback.Success){
	    //Handle successful publish
    }
    else
    {
	    //Handle unsuccessful publish
    }
});

Consume

To consume an event, the method Subscribe<T>(Func<T, Task> handlerFunction, List<int> eventTypeNumbers) where T : BrainixEvent must be called from the Brainix.GoalsCommon.RabbitMQ.Bus.IBrainixEventBus. This receives a handler function which is called as soon as a new event has been consumed. It should be noted that if this function cannot be successfully executed (an exception is caught), the event is put back into the queue and will no longer be consumed. It is also important to note that you cannot call the database directly from the handler function, because you are in a different thread and context. More information on this can be found in the corresponding documentation. Optionally, a list with the numbers of the respective event types that are to be consumed can be given to the method. This parameter determines the individual binding between the queues and exchanges that has already been explained. Here is a short example:

brainixEventBus.Subscribe<NotificationEvent>(async (notificationEvent) =>
{
    //Do something with notificationEvent
}, new List<int>
{
    (int) NotificationEvent.EventType.Information
});

Testing

For testing with the RabbitMQ bus, the IBrainixEventBus interface must be implemented by the Brainix.GoalsCommon.RabbitMQ.Bus.TestRabbitMQBus. Events can be sent and consumers defined in the integration test in the same way as in the normal implementation. However, it is important to note that the handler function of the consumer is always called in a different thread and thus executed with a time delay. This is especially important when writing to cross-thread objects within the integration test and comparing them with the expected object using Assert. It is advisable to pause the main thread for a few milliseconds to ensure that all other threads have successfully completed their work. Alternatively, you can do the ``assert'' directly in the handler function, which is cleaner in many cases, but does not cover the case where an event is never consumed.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.2-beta-311 251 12/9/2022
1.0.2-beta-307 278 12/6/2022
1.0.2-beta-305 201 12/5/2022
1.0.2-beta-303 180 12/5/2022
1.0.2-beta-300 196 11/30/2022
1.0.2-beta-298 190 11/30/2022
1.0.2-beta-296 198 11/30/2022
1.0.2-beta-292 319 11/16/2022
1.0.2-beta-290 182 11/16/2022
1.0.2-beta-288 192 11/16/2022
1.0.2-beta-286 196 11/16/2022
1.0.2-beta-283 446 10/19/2022
1.0.2-beta-282 220 10/18/2022
1.0.2-beta-280 228 10/18/2022
1.0.2-beta-279 211 10/18/2022
1.0.2-beta-277 236 10/14/2022
1.0.2-beta-270 2,083 4/19/2022
1.0.2-beta-269 255 4/19/2022
1.0.2-beta-267 260 4/19/2022
1.0.2-beta-264 346 4/18/2022
1.0.2-beta-261 255 4/15/2022
1.0.2-beta-258 262 4/15/2022
1.0.2-beta-255 260 4/12/2022
1.0.2-beta-253 318 4/5/2022
1.0.2-beta-247 262 3/28/2022
1.0.2-beta-244 356 3/16/2022
1.0.2-beta-241 245 3/13/2022
1.0.2-beta-234 522 3/9/2022
1.0.2-beta-232 446 3/8/2022
1.0.2-beta-230 253 3/8/2022
1.0.2-beta-228 246 3/8/2022
1.0.2-beta-226 260 3/8/2022
1.0.2-beta-224 259 3/8/2022
1.0.2-beta-221 259 3/8/2022
1.0.2-beta-217 270 3/8/2022
1.0.2-beta-214 271 3/6/2022
1.0.2-beta-212 403 3/2/2022
1.0.2-beta-209 269 3/2/2022
1.0.2-beta-208 823 3/2/2022
1.0.2-beta-203 323 3/1/2022
1.0.2-beta-200 645 2/28/2022
1.0.2-beta-198 268 2/27/2022
1.0.2-beta-195 270 2/26/2022
1.0.2-beta-193 266 2/26/2022
1.0.2-beta-191 262 2/26/2022
1.0.2-beta-184 559 2/11/2022
1.0.2-beta-181 290 2/9/2022
1.0.2-beta-178 516 2/5/2022
1.0.2-beta-175 255 2/5/2022
1.0.2-beta-173 245 2/5/2022
1.0.2-beta-171 331 2/4/2022
1.0.2-beta-169 276 2/3/2022
1.0.2-beta-165 393 1/31/2022
1.0.2-beta-162 283 1/31/2022
1.0.2-beta-159 308 1/29/2022
1.0.2-beta-154 574 1/25/2022
1.0.2-beta-152 268 1/25/2022
1.0.2-beta-147 385 1/24/2022
1.0.2-beta-145 296 1/24/2022
1.0.2-beta-141 295 1/21/2022
1.0.2-beta-139 280 1/20/2022
1.0.2-beta-132 274 1/19/2022
1.0.2-beta-125 438 1/18/2022
1.0.2-beta-000 276 1/19/2022
1.0.1 613 1/18/2022
1.0.1-beta-120 260 1/18/2022
1.0.0-beta-99 273 1/17/2022
1.0.0-beta-96 261 1/16/2022
1.0.0-beta-94 268 1/16/2022
1.0.0-beta-92 277 1/16/2022
1.0.0-beta-9 275 1/6/2022
1.0.0-beta-88 330 1/15/2022
1.0.0-beta-85 291 1/14/2022
1.0.0-beta-82 267 1/14/2022
1.0.0-beta-80 257 1/14/2022
1.0.0-beta-78 278 1/14/2022
1.0.0-beta-75 286 1/11/2022
1.0.0-beta-73 337 1/11/2022
1.0.0-beta-71 265 1/11/2022
1.0.0-beta-7 322 1/6/2022
1.0.0-beta-69 284 1/11/2022
1.0.0-beta-67 274 1/11/2022
1.0.0-beta-65 265 1/11/2022
1.0.0-beta-63 330 1/11/2022
1.0.0-beta-61 258 1/11/2022
1.0.0-beta-58 261 1/11/2022
1.0.0-beta-56 269 1/11/2022
1.0.0-beta-53 291 1/10/2022
1.0.0-beta-51 280 1/10/2022
1.0.0-beta-50 278 1/10/2022
1.0.0-beta-48 275 1/10/2022
1.0.0-beta-46 279 1/10/2022
1.0.0-beta-44 267 1/10/2022
1.0.0-beta-42 352 1/8/2022
1.0.0-beta-40 278 1/8/2022
1.0.0-beta-4 267 1/6/2022
1.0.0-beta-38 288 1/8/2022
1.0.0-beta-36 272 1/8/2022
1.0.0-beta-35 258 1/8/2022
1.0.0-beta-32 276 1/8/2022
1.0.0-beta-26 270 1/8/2022
1.0.0-beta-24 276 1/8/2022
1.0.0-beta-22 260 1/8/2022
1.0.0-beta-20 278 1/8/2022
1.0.0-beta-15 280 1/8/2022
1.0.0-beta-13 272 1/7/2022
1.0.0-beta-128 262 1/19/2022
1.0.0-beta-112 262 1/18/2022
1.0.0-beta-109 261 1/18/2022
1.0.0-beta-104 278 1/17/2022