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 247 12/9/2022
1.0.2-beta-307 274 12/6/2022
1.0.2-beta-305 197 12/5/2022
1.0.2-beta-303 176 12/5/2022
1.0.2-beta-300 192 11/30/2022
1.0.2-beta-298 185 11/30/2022
1.0.2-beta-296 193 11/30/2022
1.0.2-beta-292 315 11/16/2022
1.0.2-beta-290 178 11/16/2022
1.0.2-beta-288 188 11/16/2022
1.0.2-beta-286 192 11/16/2022
1.0.2-beta-283 442 10/19/2022
1.0.2-beta-282 216 10/18/2022
1.0.2-beta-280 224 10/18/2022
1.0.2-beta-279 207 10/18/2022
1.0.2-beta-277 232 10/14/2022
1.0.2-beta-270 2,079 4/19/2022
1.0.2-beta-269 251 4/19/2022
1.0.2-beta-267 256 4/19/2022
1.0.2-beta-264 342 4/18/2022
1.0.2-beta-261 251 4/15/2022
1.0.2-beta-258 258 4/15/2022
1.0.2-beta-255 256 4/12/2022
1.0.2-beta-253 314 4/5/2022
1.0.2-beta-247 258 3/28/2022
1.0.2-beta-244 352 3/16/2022
1.0.2-beta-241 241 3/13/2022
1.0.2-beta-234 518 3/9/2022
1.0.2-beta-232 442 3/8/2022
1.0.2-beta-230 249 3/8/2022
1.0.2-beta-228 242 3/8/2022
1.0.2-beta-226 256 3/8/2022
1.0.2-beta-224 255 3/8/2022
1.0.2-beta-221 253 3/8/2022
1.0.2-beta-217 266 3/8/2022
1.0.2-beta-214 266 3/6/2022
1.0.2-beta-212 399 3/2/2022
1.0.2-beta-209 265 3/2/2022
1.0.2-beta-208 819 3/2/2022
1.0.2-beta-203 319 3/1/2022
1.0.2-beta-200 641 2/28/2022
1.0.2-beta-198 264 2/27/2022
1.0.2-beta-195 266 2/26/2022
1.0.2-beta-193 262 2/26/2022
1.0.2-beta-191 258 2/26/2022
1.0.2-beta-184 555 2/11/2022
1.0.2-beta-181 286 2/9/2022
1.0.2-beta-178 512 2/5/2022
1.0.2-beta-175 251 2/5/2022
1.0.2-beta-173 241 2/5/2022
1.0.2-beta-171 326 2/4/2022
1.0.2-beta-169 272 2/3/2022
1.0.2-beta-165 389 1/31/2022
1.0.2-beta-162 279 1/31/2022
1.0.2-beta-159 304 1/29/2022
1.0.2-beta-154 570 1/25/2022
1.0.2-beta-152 264 1/25/2022
1.0.2-beta-147 381 1/24/2022
1.0.2-beta-145 292 1/24/2022
1.0.2-beta-141 292 1/21/2022
1.0.2-beta-139 276 1/20/2022
1.0.2-beta-132 270 1/19/2022
1.0.2-beta-125 434 1/18/2022
1.0.2-beta-000 272 1/19/2022
1.0.1 609 1/18/2022
1.0.1-beta-120 256 1/18/2022
1.0.0-beta-99 269 1/17/2022
1.0.0-beta-96 257 1/16/2022
1.0.0-beta-94 264 1/16/2022
1.0.0-beta-92 273 1/16/2022
1.0.0-beta-9 271 1/6/2022
1.0.0-beta-88 326 1/15/2022
1.0.0-beta-85 287 1/14/2022
1.0.0-beta-82 263 1/14/2022
1.0.0-beta-80 253 1/14/2022
1.0.0-beta-78 274 1/14/2022
1.0.0-beta-75 282 1/11/2022
1.0.0-beta-73 333 1/11/2022
1.0.0-beta-71 261 1/11/2022
1.0.0-beta-7 318 1/6/2022
1.0.0-beta-69 280 1/11/2022
1.0.0-beta-67 269 1/11/2022
1.0.0-beta-65 261 1/11/2022
1.0.0-beta-63 326 1/11/2022
1.0.0-beta-61 254 1/11/2022
1.0.0-beta-58 257 1/11/2022
1.0.0-beta-56 265 1/11/2022
1.0.0-beta-53 287 1/10/2022
1.0.0-beta-51 276 1/10/2022
1.0.0-beta-50 274 1/10/2022
1.0.0-beta-48 271 1/10/2022
1.0.0-beta-46 275 1/10/2022
1.0.0-beta-44 263 1/10/2022
1.0.0-beta-42 348 1/8/2022
1.0.0-beta-40 274 1/8/2022
1.0.0-beta-4 262 1/6/2022
1.0.0-beta-38 284 1/8/2022
1.0.0-beta-36 268 1/8/2022
1.0.0-beta-35 254 1/8/2022
1.0.0-beta-32 272 1/8/2022
1.0.0-beta-26 266 1/8/2022
1.0.0-beta-24 272 1/8/2022
1.0.0-beta-22 256 1/8/2022
1.0.0-beta-20 274 1/8/2022
1.0.0-beta-15 276 1/8/2022
1.0.0-beta-13 268 1/7/2022
1.0.0-beta-128 258 1/19/2022
1.0.0-beta-112 258 1/18/2022
1.0.0-beta-109 257 1/18/2022
1.0.0-beta-104 274 1/17/2022