Sidub.Messaging 1.1.8

Sidub Messaging - Messaging

This repository contains the messaging module for Sidub Messaging. It provides services and abstractions to enable the use of asynchronous messaging services in combination with concepts defined within the Sidub Platform (i.e., entity).

Currently this package includes the SignalR messaging connector as it is the only implementation available at this time. Future releases will separate the providers into their own packages to allow for more granular control over the dependencies.

Main Concepts

Messaging service (IMessagingService)

The messaging service is the primary interface for sending and receiving messages. It provides methods for sending and receiving messages from specific messaging hubs defined within the IServiceRegistry. Depending the type of IMessagingConnector that is registered, the messaging service will leverage the appropriate provider to send and receive messages.

Usage

Registering a messaging service

Service registration occurs as part of the Sidub Platform initialization. When registering the Sidub Platform, register a messaging service with the appropriate IMessagingConnector for your service implementation.

For example, to register an Azure SignalR messaging service:

// this should be defined in a static class or similar for ease of access (i.e., ServiceReferences.MessagingService)...
var MessagingService = new MessagingServiceReference("ChatroomApi");

// sample only, these would be dynamic...
var email = "my@email.com";
var name = "My Name";

services.AddSidubPlatform(provider =>
{
    var licensingOptions = provider.GetRequiredService<IOptionsSnapshot<LicensingServiceOptions>>().Value
        ?? throw new Exception("Failed to retrieve LicensingServiceOptions instance.");

    var metadata = new InMemoryServiceRegistry();

    // register your license...
    metadata.RegisterLicense(licensingOptions);

    // register the messaging service...
    var messageServiceConnector = new SignalRConnector(@"https://my-test-chatroom.azurewebsites.net/api/", "Chatroom");
    metadata.RegisterServiceReference(MessagingService, messageServiceConnector);

    // register the identity service for messaging...
    //  - generic credential used as example; token-based credentials would be the preferred method...
    var messageServiceIdentityReference = new AuthenticationServiceReference("Chatroom-Identity");
    var messageServiceIdentity = new GenericUserCredential(email, name);

    metadata.RegisterServiceReference(messageServiceIdentityReference, messageServiceIdentity, MessagingService);

    return metadata;
});

Subscribing to messages

To subscribe to messages, use the IMessagingService.Subscribe<TEntity> method. This method will register the provided callback to be invoked when a message of the specified type is received. Available to the delegate is a MessageEnvelope<TEntity> object, which contains information about the message and the message itself.

await messagingService.Subscribe<ChatMessage>(ServiceReferences.MessagingService, async envelope =>
{
    await Task.Run(() => Console.WriteLine($"{envelope.Author}@{envelope.CreatedOn}: {envelope.Message.Message}"));
});

Broadcasting messages

To broadcast messages, use the IMessagingService.Broadcast<TEntity> method. This method will send the provided message to all subscribers of the specified type.

var messageText = "This is a test message...";

var message = new ChatMessage()
{
    Message = messageText
};

await messagingService.Broadcast(ServiceReferences.MessagingService, message);

License

This project is licensed under a proprietary license. For details, see https://sidub.ca/licensing or the LICENSE.txt file.