You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Orleans](https://github.com/dotnet/orleans) is a framework that provides a straight-forward approach to building distributed high-scale computing applications, without the need to learn and apply complex concurrency or other scaling patterns.
12
+
[Orleans](https://learn.microsoft.com/en-us/dotnet/orleans/overview) is a cross-platform framework for building robust, scalable distributed applications. Distributed applications are defined as apps that span more than a single process, often beyond hardware boundaries using peer-to-peer communication. Orleans scales from a single on-premises server to hundreds to thousands of distributed, highly available applications in the cloud. [See Orleans source code on Github](https://github.com/dotnet/orleans)
13
13
14
-
[ASP.NET Core SignalR](https://github.com/aspnet/SignalR) is a new library for ASP.NET Core developers that makes it incredibly simple to add real-time web functionality to your applications. What is "real-time web" functionality? It's the ability to have your server-side code push content to the connected clients as it happens, in real-time.
14
+
[ASP.NET Core SignalR](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction?view=aspnetcore-7.0) is an open-source library that simplifies adding real-time web functionality to apps. Real-time web functionality enables server-side code to push content to clients instantly.
15
15
16
-
**SignalR.Orleans** is a package that allow us to enhance the _real-time_ capabilities of SignalR by leveraging Orleans distributed cloud platform capabilities.
16
+
**SignalR.Orleans** is a package that gives you two abilities:
17
17
18
+
1. Use your Orleans cluster as a backplane for SignalR. [Learn about scaling out SignalR on multiple servers.](https://learn.microsoft.com/en-us/aspnet/core/signalr/scale?view=aspnetcore-7.0)
19
+
20
+
> There are various choices of backplane that you can use for SignalR, as you will see in the link above. If you're already using Orleans, then you might want to use Orleans as the backplane to reduce the number of dependencies used by your application and to reduce the number of network hops (and latency) that would be required when calling an external service.
21
+
22
+
2. Send messages from Orleans grains to SignalR clients.
23
+
24
+
> If the SignalR component of your application is cohosted with Orleans (same server, same process and `Microsoft.AspNetCore.SignalR.IHubContext<MyHub>` can be injected into an Orleans gain), you already have this ability without installing this package.
25
+
26
+
> However, if the SignalR component of your application is "remote" from the grains, this package will give the grains a way of sending messages to SignalR clients by injecting `SignalR.Orleans.Core.HubContext<MyHub>`.
27
+
28
+
TODO: These two abilities should be provided independently of each other. Unfortunately at this stage, ability #2 is only provided if ability #1 is used as well.
18
29
19
30
# Installation
20
31
21
-
Installation is performed via [NuGet](https://www.nuget.org/packages/SignalR.Orleans/)
32
+
Installation is performed via [NuGet.](https://www.nuget.org/packages/SignalR.Orleans/)
33
+
34
+
Packages with version `7.x.x` are compatible with Orleans `v7.x.x` and above. If you're still using an earlier version of Orleans, you will need to use earlier versions of the package.
22
35
23
-
From Package Manager:
36
+
Package Manager:
24
37
25
38
> PS> Install-Package SignalR.Orleans
26
39
@@ -32,9 +45,150 @@ Paket:
32
45
33
46
> \# paket add SignalR.Orleans
34
47
35
-
# Configuration
48
+
---
49
+
# Version 7.0.0 documentation
50
+
> Scroll down to see documentation for earlier versions.
51
+
52
+
Here is a complete starter example featuring cohosted aspnetcore app with SignalR and Orleans.
53
+
54
+
```csharp
55
+
usingMicrosoft.AspNetCore.SignalR;
56
+
usingOrleans.Hosting;
57
+
usingSignalR.Orleans;
58
+
59
+
// Create a host that can cohost aspnetcore AND orleans together in a single process.
60
+
varbuilder=WebApplication.CreateBuilder(args);
61
+
builder.Host.UseOrleans(siloBuilder=>
62
+
{
63
+
siloBuilder.UseLocalhostClustering();
64
+
siloBuilder.UseSignalR(); // Adds ability #1 and #2 to Orleans.
65
+
siloBuilder.RegisterHub<MyHub>(); // Required for each hub type if the backplane ability #1 is being used.
66
+
});
67
+
68
+
builder.Services
69
+
.AddSignalR() // Adds SignalR hubs to the web application
70
+
.AddOrleans(); // Tells the SignalR hubs in the web application to use Orleans as a backplane (ability #1)
71
+
72
+
varapp=builder.Build();
73
+
app.MapHub<MyHub>("/myhub");
74
+
awaitapp.RunAsync();
75
+
76
+
// A SignalR Hub. https://learn.microsoft.com/en-us/aspnet/core/signalr/hubs?view=aspnetcore-7.0
77
+
classMyHub : Hub
78
+
{
79
+
}
80
+
```
81
+
82
+
### Silo configuration - grain storage
83
+
84
+
The SignalR.Orleans backplane (ability #1) uses grains under the hood that use storage to keep track of where each SignalR client is connected and what groups it belongs to. The storage used by default is `MemoryStorage`.
85
+
86
+
Use the given storage name constant to configure the correct storage provider.
### Silo configuration - stream type and stream storage
102
+
103
+
SignalR.Orleans uses streams under the hood to provide the backplane (ability #1). The default stream type is `MemoryStream`. All streams in a given Orleans instance must use the same storage provider, named `PubSubStore`, currently defaulted to `MemoryStorage`.
104
+
105
+
```csharp
106
+
// FIRST customize the storage used by ALL stream providers in the entire Orleans host:
107
+
// Remember, memory storage won't work if you're using a cluster.
If the SignalR app is cohosted as demonstrated above, you don't need this package to send messages from an Orleans grain. Simply inject `IHubContext<MyHub>` to the grain's constructor and call its methods to send messages. [Read more about it here.](https://learn.microsoft.com/en-us/aspnet/core/signalr/hubcontext?view=aspnetcore-7.0)
120
+
121
+
However, if the SignalR app is not cohosted, and if it's using Orleans as a backplane, then it's possible to use this package to send messages to the SignalR clients using the backplane streams in Orleans as a conduit (ability #2).
// Send a message to all connections made by a particular authenticated user
145
+
await_hubContext.Group("someUserId").Send(msg);
146
+
147
+
// TODO: We have not implemented ability to send a message to ALL clients yet.
148
+
}
149
+
}
150
+
```
151
+
152
+
## Configuring the `IClusterClient`
153
+
If your SignalR app is cohosted with Orleans, it will automatically grab an `IClusterClient` from the service provider and connect to the Orleans backplane.
154
+
155
+
However, if it's not cohosted, you'll have to give it an `IClusterClient` to use:
156
+
157
+
```csharp
158
+
usingMicrosoft.AspNetCore.SignalR;
159
+
usingOrleans.Hosting;
160
+
usingSignalR.Orleans;
161
+
162
+
// Create a web application that will connect to a remote Orleans cluster
163
+
varbuilder=WebApplication.CreateBuilder(args);
164
+
builder.Services
165
+
// Adds an IClusterClient to the service provider.
166
+
.AddOrleansClient(clientBuilder=>
167
+
{
168
+
// Tell the client how to connect to Orleans (you'll need to customize this for yourself)
169
+
clientBuilder.UseLocalhostClustering();
170
+
// Tells the client how to connect to the SignalR.Orleans backplane.
171
+
clientBuilder.UseSignalR(configure: null);
172
+
})
173
+
.AddSignalR() // Adds SignalR hubs to the web application
174
+
.AddOrleans(); // Tells SignalR to use Orleans as a backplane (ability #1)
175
+
176
+
varapp=builder.Build();
177
+
app.MapHub<MyHub>("/myhub");
178
+
awaitapp.RunAsync();
179
+
180
+
// A SignalR Hub. https://learn.microsoft.com/en-us/aspnet/core/signalr/hubs?view=aspnetcore-7.0
181
+
classMyHub : Hub
182
+
{
183
+
}
184
+
```
185
+
186
+
This is the end of documentation for versions >= 7.0.0. Below is older documenation for previous versions.
187
+
188
+
---
189
+
# Earlier version documentation
36
190
37
-
## Silo
191
+
## Configure the Silo
38
192
We need to configure the Orleans Silo with the below:
39
193
* Use `.UseSignalR()` on `ISiloHostBuilder`.
40
194
* Make sure to call `RegisterHub<THub>()` where `THub` is the type of the Hub you want to be added to the backplane.
0 commit comments