RossWright.MetalShout.Server 1.0.0-alpha6.6

MetalShout

by Ross Wright

Copyright 2023 Pross Co. All Rights Reserved.

Description

Easily push objects from the server to the client

Licensing

To use this library you must attain and embed a license file from RossWright.com. Simply include the file in a project with Build Action to Embedded Resource.

Pre-requisites

MetalShout requires MetalGuardian

Client Setup

To setup MetalShout on the client, reference the RossWright.MetalShout package and in Program.cs call: builder.Services.AddPushService();

A push message can be any class known to both the client and server that can be serialized (no circular references, etc.).

To subscribe to a push on the client, inject the RossWright.MetalShout.IPushService and then there are two ways to subscribe to push messages from the server.

First, you can simply provide a closure...

[Inject] public RossWright.MetalShout.IPushService pushService { get; set; } = null!;
...
var subscription = pushService.Subscribe<PushObj>(pushObj => /* handle the received pushObj here */);

and then in when you no longer need the push (such as a DisposeAsync method for your page) call await pushService.Unsubscribe(subscription); or await subscription.DisposeAsync();

OR, the second way to to define a subscriber class that implements IPushSubscriber such as:

public class PushObjSubscriber : IPushSubscriber<PushObj>
{
	public Task OnPushReceived(PushObj message)
	{
		// process the incoming push object here
	}
}

and then where appropriate, perhaps in your program.cs or page initialization code...

[Inject] public IPushService pushService { get; set; } = null!;
...
var subscriber = new PushObjSubscriber();
pushService.Subscribe(subscriber);

and then in when you no longer need the push (such as a DisposeAsync method for your page) call

await pushService.Unsubscribe(subscriber);

The examples above assume the client is connecting to a server on the default connection as setup by AddMetalGuardianHttpClient. To connect to a different server, pass the connection name provided to Metal Guardian in the Subscribe and Unsubscribe calls.

Server Setup

To setup MetalShout on the server, reference the RossWright.MetalShout.Server package and in Program.cs call: builder.Services.AddPushService(); before the call to builder.Build() and app.UsePushService() after builder.Build() but before app.Run()

For a client to receive a push message, code on the server must subscribe the user to the message. To subscribe a user to a push message type inject the IPushSubscriptionRepository and call Subscribe<PushObj>(userId)

When you need to push a message to a client, inject the IPushService and call Push with the object to be pushed Push(new PushObj())

A reference ID can be supplied to both the Subscribe and Push to more finely control which instances of a push are sent to whom.

User IDs can also be specified as a parameter to Push to override the Push Subscription Repositor subscriptions.

Your server can also detect connections to the push server by registering one or more services as IPushConnectionObserver

Notes

The default SignalR Hub for MetalShout is "PushHub". You can change this by passing a parameter to the AddPushService call on the client and the UsePushService call on the server.