This is the official .NET library for interacting with the Channels WebSocket API.
Register at pusher.com/channels and use the application credentials within your app as shown below.
More general documentation can be found on the Official Channels Documentation.
For reporting issues, bugs, and feature requests, please feel free to open a pull request or open an issue. If you do not receive a timely response, feel free to check our support portal.
For integrating Pusher Channels with Unity follow the instructions at https://github.com/pusher/pusher-websocket-unity
- .NET Standard 1.3
- .NET Standard 2.0
- .NET 4.5
- .NET 4.7.2
- Unity 2018 and greater via pusher-websocket-unity
- Pusher Channels .NET Client library
- Supported platforms
- Contents
- Installation
- API
- Configuration
- Connecting
- Subscribing
- Subscription Count Handler
- User authentication
- Binding to events
- Triggering events
- Developer notes
- Testing
- Code signing key generation
- Migrating from version 1 to version 2
- Changed in the Pusher class
- Removed from the Pusher class
- Removed from the Channel class
- Removed from the GenericPresenceChannel class
- Removed from the ConnectionState enum
- Changed in the GenericPresenceChannel class
- Added to the Pusher class
- Added to the GenericPresenceChannel class
- Added to the ErrorCodes enum
- License
The compiled library is available on NuGet:
Install-Package PusherClient
Here's the API in a nutshell.
class ChatMember
{
public string Name { get; set; }
}
class ChatMessage : ChatMember
{
public string Message { get; set; }
}
// Raised when Pusher is ready
AutoResetEvent readyEvent = new AutoResetEvent(false);
// Raised when Pusher is done
AutoResetEvent doneEvent = new AutoResetEvent(false);
// Create Pusher client ready to subscribe to public, private and presence channels
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
Encrypted = true,
});
// Lists all current presence channel members
void ListMembers(GenericPresenceChannel<ChatMember> channel)
{
Dictionary<string, ChatMember> members = channel.GetMembers();
foreach (var member in members)
{
Trace.TraceInformation($"Id: {member.Key}, Name: {member.Value.Name}");
}
}
// MemberAdded event handler
void ChatMemberAdded(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has joined");
if (sender is GenericPresenceChannel<ChatMember> channel)
{
ListMembers(channel);
}
}
// MemberRemoved event handler
void ChatMemberRemoved(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has left");
if (sender is GenericPresenceChannel<ChatMember> channel)
{
ListMembers(channel);
}
}
// Handle errors
void HandleError(object sender, PusherException error)
{
if ((int)error.PusherCode < 5000)
{
// Error recevied from Pusher cluster, use PusherCode to filter.
}
else
{
if (error is ChannelUnauthorizedException unauthorizedAccess)
{
// Private and Presence channel failed authorization with Forbidden (403)
}
else if (error is ChannelAuthorizationFailureException httpError)
{
// Authorization endpoint returned an HTTP error other than Forbidden (403)
}
else if (error is OperationTimeoutException timeoutError)
{
// A client operation has timed-out. Governed by PusherOptions.ClientTimeout
}
else if (error is ChannelDecryptionException decryptionError)
{
// Failed to decrypt the data for a private encrypted channel
}
else
{
// Handle other errors
}
}
Trace.TraceError($"{error}");
}
// Subscribed event handler
void SubscribedHandler(object sender, Channel channel)
{
if (channel is GenericPresenceChannel<ChatMember> presenceChannel)
{
ListMembers(presenceChannel);
}
else if (channel.Name == "private-chat-channel-1")
{
// Trigger event
channel.Trigger("client-chat-event", new ChatMessage
{
Name = "Joe",
Message = "Hello from Joe!",
});
}
}
// Connection state change event handler
void StateChangedEventHandler(object sender, ConnectionState state)
{
Trace.TraceInformation($"SocketId: {((Pusher)sender).SocketID}, State: {state}");
if (state == ConnectionState.Connected)
{
readyEvent.Set();
readyEvent.Reset();
}
if (state == ConnectionState.Disconnected)
{
doneEvent.Set();
doneEvent.Reset();
}
}
// Bind events
void BindEvents(object sender)
{
Pusher _pusher = sender as Pusher;
Channel _channel = _pusher.GetChannel("private-chat-channel-1");
_channel.Bind("client-chat-event", (PusherEvent eventData) =>
{
ChatMessage data = JsonConvert.DeserializeObject<ChatMessage>(eventData.Data);
Trace.TraceInformation($"[{data.Name}] {data.Message}");
});
}
// Unbind events
void UnbindEvents(object sender)
{
((Pusher)sender).UnbindAll();
}
// Add event handlers
pusher.Connected += BindEvents;
pusher.Disconnected += UnbindEvents;
pusher.Subscribed += SubscribedHandler;
pusher.ConnectionStateChanged += StateChangedEventHandler;
pusher.Error += HandleError;
// Create subscriptions
await pusher.SubscribeAsync("public-channel-1").ConfigureAwait(false);
await pusher.SubscribeAsync("private-chat-channel-1").ConfigureAwait(false);
GenericPresenceChannel<ChatMember> memberChannel =
await pusher.SubscribePresenceAsync<ChatMember>("presence-channel-1").ConfigureAwait(false);
memberChannel.MemberAdded += ChatMemberAdded;
memberChannel.MemberRemoved += ChatMemberRemoved;
// Connect
try
{
await pusher.ConnectAsync().ConfigureAwait(false);
}
catch (Exception)
{
// We failed to connect, handle the error.
// You will also receive the error via
// HandleError(object sender, PusherException error)
throw;
}
Assert.AreEqual(ConnectionState.Connected, pusher.State);
Assert.IsTrue(readyEvent.WaitOne(TimeSpan.FromSeconds(5)));
// Remove subscriptions
await pusher.UnsubscribeAllAsync().ConfigureAwait(false);
// Disconnect
await pusher.DisconnectAsync().ConfigureAwait(false);
Assert.AreEqual(ConnectionState.Disconnected, pusher.State);
Assert.IsTrue(doneEvent.WaitOne(TimeSpan.FromSeconds(5)));
See the example app for details.
Constructing a Pusher client requires some options. These options are defined in a PusherOptions
object:
Property | Type | Description |
---|---|---|
Authorizer | IAuthorizer | Required for authorizing private and presence channel subscriptions. |
ClientTimeout | TimeSpan | The timeout period to wait for an asynchrounous operation to complete. The default value is 30 seconds. |
Cluster | String | The Pusher host cluster name; for example, "eu". The default value is "mt1". |
Encrypted | Boolean | Indicates whether the connection will be encrypted. The default value is false . |
TraceLogger | ITraceLogger | Used for tracing diagnostic events. Should not be set in production code. |
The Pusher client constructor requires an application key which you can get from the app's API Access section in the Pusher Channels dashboard. It also takes a PusherOptions object as an input parameter.
Examples:
Construction of a public channel only subscriber
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Cluster = Config.Cluster,
Encrypted = true,
});
Construction of authorized private and presence channels subscriber
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new HttpAuthorizer("http://localhost:8888/auth/Jane"),
Cluster = Config.Cluster,
Encrypted = true,
});
Specifying a client timeout
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new HttpAuthorizer("http://localhost:8888/auth/Jane"),
Cluster = Config.Cluster,
Encrypted = true,
ClientTimeout = TimeSpan.FromSeconds(20),
});
You can access the current connection state using Pusher.State
and bind to state changes using Pusher.ConnectionStateChanged
.
Possible States:
- Uninitialized: Initial state; no event is emitted in this state.
- Connecting: The channel client is attempting to connect.
- Connected: The channel connection is open and authenticated with your app. Channel subscriptions can now be made.
- Disconnecting: The channel client is attempting to disconnect.
- Disconnected: The channel connection is disconnected and all subscriptions have stopped.
- WaitingToReconnect: Once connected the channel client will automatically attempt to reconnect if there is a connection failure.
First call to Pusher.ConnectAsync()
succeeds:
Uninitialized -> Connecting -> Connected
. Auto reconnect is enabled.
First call to Pusher.ConnectAsync()
fails:
Uninitialized -> Connecting
. Auto reconnect is disabled.
Pusher.ConnectAsync()
will throw an exception and a Pusher.Error
will be emitted.
Call to Pusher.DisconnectAsync()
succeeds:
Connected -> Disconnecting -> Disconnected
. Auto reconnect is disabled.
Call to Pusher.DisconnectAsync()
fails:
Connected -> Disconnecting
.
Pusher.DisconnectAsync()
will throw an exception.
Sample code:
pusher = new Pusher("YOUR_APP_KEY");
pusher.ConnectionStateChanged += StateChanged;
pusher.Error += ErrorHandler;
void StateChanged(object sender, ConnectionState state)
{
Console.WriteLine("Connection state: " + state.ToString());
}
void ErrorHandler(object sender, PusherException error)
{
Console.WriteLine("Pusher error: " + error.ToString());
}
try
{
await pusher.ConnectAsync().ConfigureAwait(false);
// pusher.State will be ConnectionState.Connected
}
catch(Exception error)
{
// Handle error
}
After entering a state of Connected
, auto reconnect is enabled. If the connection is dropped the channel client will attempt to re-establish the connection.
Here is a possible scenario played out after a connection failure.
- Connection dropped
- State transition:
Connected -> Disconnected
- State transition:
Disconnected -> WaitingToReconnect
- Pause for 1 second and attempt to reconnect
- State transition:
WaitingToReconnect -> Connecting
- Connection attempt fails, network still down
- State transition:
Connecting -> Disconnected
- State transition:
Disconnected -> WaitingToReconnect
- Pause for 2 seconds (max 10 seconds) and attempt to reconnect
- State transition:
WaitingToReconnect -> Connecting
- Connection attempt succeeds
- State transition:
Connecting -> Connected
After disconnecting, all subscriptions are stopped and no events will be received from the Pusher server host. Calling ConnectAsync will re-enable any subscriptions that were stopped when disconnecting. To permanently stop receiving events, unsubscribe from the channel.
// Disconnect
await pusher.DisconnectAsync().ConfigureAwait(false);
Assert.AreEqual(ConnectionState.Disconnected, pusher.State);
The Pusher client has delegates for Connected
and Disconnected
events.
The Connected
event is raised after connecting to the cluster host.
The Disconnected
event is raised after disconnecting from the cluster host.
Sample code:
pusher = new Pusher("YOUR_APP_KEY", new PusherOptions(){
Authorizer = new HttpAuthorizer("YOUR_ENDPOINT")
});
pusher.Connected += OnConnected;
pusher.Disconnected += OnDisconnected;
void OnConnected(object sender)
{
Console.WriteLine("Connected: " + ((Pusher)sender).SocketID);
}
void OnDisconnected(object sender)
{
Console.WriteLine("Disconnected: " + ((Pusher)sender).SocketID);
}
try
{
await pusher.ConnectAsync().ConfigureAwait(false);
// pusher.State will now be ConnectionState.Connected
}
catch(Exception error)
{
// Handle error
}
do
{
line = Console.ReadLine();
if (line == "quit") break;
} while (line != null);
// Disconnect
await pusher.DisconnectAsync().ConfigureAwait(false);
// pusher.State will now be ConnectionState.Disconnected
Three types of channels are supported
- Public channels: can be subscribed to by anyone who knows their name.
- Private channels: are private in that you control access to who can subscribe to the channel.
- Presence channels: are extensions to private channels and let you add user information on a subscription, and let other members of the channel know who is online.
There are two modes for creating channel subscriptions
- Pre-connecting: setup all subscriptions first and then connect using
Pusher.ConnectAsync
. This is a purely asynchronous model. The subscriptions are created asynchronously after connecting. Error detection needs to be done via the error delegatePusher.Error
. - Post-connecting: setup all subscriptions after connecting using
Pusher.ConnectAsync
. This is a partly synchronous model. The subscriptions are created synchronously. If the method call fails; for example, the user is not authorized, an exception will be thrown. You will also receive an error via the delegatePusher.Error
.
Regardless of the mode used, it is good to have error handling via the Pusher.Error
delegate. For example, if you were to lose the network connection and the client attempts to auto reconnect, things happen asynchronously and the error handler is the only way to detect errors. Here is a sample error handler:
void ErrorHandler(object sender, PusherException error)
{
if ((int)error.PusherCode < 5000)
{
// Error recevied from Pusher cluster, use PusherCode to filter.
}
else
{
if (error is ChannelUnauthorizedException unauthorizedAccess)
{
// Private and Presence channel failed authorization with Forbidden (403)
}
else if (error is ChannelAuthorizationFailureException httpError)
{
// Authorization endpoint returned an HTTP error other than Forbidden (403)
}
else if (error is OperationTimeoutException timeoutError)
{
// A client operation has timed-out. Governed by PusherOptions.ClientTimeout
}
else if (error is ChannelDecryptionException decryptionError)
{
// Failed to decrypt the data for a private encrypted channel
}
else
{
// Handle other errors
}
}
}
ErrorHandler will be referred to in the channel subscription examples.
Setting up a public channel subscription before connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Subscribe
Channel channel = await pusher.SubscribeAsync("public-channel-1").ConfigureAwait(false);
Assert.AreEqual(false, channel.IsSubscribed);
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
Setting up a public channel subscription after connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
// Subscribe
try
{
Channel channel = await pusher.SubscribeAsync("public-channel-1").ConfigureAwait(false);
Assert.AreEqual(true, channel.IsSubscribed);
}
catch (Exception)
{
// Handle error
}
The name of a private channel needs to start with private-
.
It's possible to subscribe to private channels that provide a mechanism for authorizing channel subscriptions. In order to do this you need to provide an IAuthorizer
when creating the Pusher
instance.
The library provides an HttpAuthorizer
implementation of IAuthorizer
which makes an HTTP POST
request to an authenticating endpoint. However, you can implement your own authentication mechanism if required.
Setting up a private channel subscription before connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Subscribe
Channel channel = await pusher.SubscribeAsync("private-chat-channel-1").ConfigureAwait(false);
Assert.AreEqual(false, channel.IsSubscribed);
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
Setting up a private channel subscription after connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
try
{
// Subscribe
Channel channel = await pusher.SubscribeAsync("private-chat-channel-1").ConfigureAwait(false);
Assert.AreEqual(true, channel.IsSubscribed);
}
catch (ChannelUnauthorizedException)
{
// Handle client unauthorized error
}
catch (Exception)
{
// Handle other errors
}
Similar to Private channels, you can also subscribe to a private encrypted channel. This library now fully supports end-to-end encryption. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them.
Like the private channel, you must provide your own authentication endpoint, with your own encryption master key. There is a demonstration endpoint in the repo to look at using Nancy.
To get started you need to subscribe to your channel and bind to the events you are interested in; for example:
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new HttpAuthorizer("http://localhost:8888/auth/joe"),
Cluster = "eu",
Encrypted = true,
});
// Listen for secret events
void GeneralListener(string eventName, PusherEvent eventData)
{
if (eventName == "secret-event")
{
ChatMessage data = JsonConvert.DeserializeObject<ChatMessage>(eventData.Data);
Console.WriteLine($"{Environment.NewLine}[{data.Name}] {data.Message}");
}
}
// Handle decryption error
void DecryptionErrorHandler(object sender, PusherException error)
{
if (error is ChannelDecryptionException exception)
{
string errorMsg = $"{Environment.NewLine}Decryption of message failed";
errorMsg += $" for ('{exception.ChannelName}',";
errorMsg += $" '{exception.EventName}', ";
errorMsg += $" '{exception.SocketID}')";
errorMsg += $" for reason:{Environment.NewLine}{error.Message}";
Console.WriteLine(errorMsg);
}
}
// Subcribe to private encrypted channel
pusher.Error += DecryptionErrorHandler;
pusher.BindAll(GeneralListener);
await pusher.SubscribeAsync("private-encrypted-channel").ConfigureAwait(false);
await pusher.ConnectAsync().ConfigureAwait(false);
See the example app for the Pusher client implementation.
The name of a presence channel needs to start with presence-
.
The recommended way of subscribing to a presence channel is to use the SubscribePresenceAsync
function, as opposed to the standard subscribe function. This function returns a strongly typed presence channel object with extra presence channel specific functions available to it, such as GetMember
and GetMembers
.
Setting up a presence channel subscription before connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Lists all current presence channel members
void ListMembers(GenericPresenceChannel<ChatMember> channel)
{
Dictionary<string, ChatMember> members = channel.GetMembers();
foreach (var member in members)
{
Trace.TraceInformation($"Id: {member.Key}, Name: {member.Value.Name}");
}
}
// MemberAdded event handler
void ChatMemberAdded(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has joined");
ListMembers(sender as GenericPresenceChannel<ChatMember>);
}
// MemberRemoved event handler
void ChatMemberRemoved(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has left");
ListMembers(sender as GenericPresenceChannel<ChatMember>);
}
// Subscribe
GenericPresenceChannel<ChatMember> memberChannel =
await pusher.SubscribePresenceAsync<ChatMember>("presence-channel-1").ConfigureAwait(false);
memberChannel.MemberAdded += ChatMemberAdded;
memberChannel.MemberRemoved += ChatMemberRemoved;
Assert.AreEqual(false, memberChannel.IsSubscribed);
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
Setting up a presence channel subscription after connecting
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Lists all current presence channel members
void ListMembers(GenericPresenceChannel<ChatMember> channel)
{
Dictionary<string, ChatMember> members = channel.GetMembers();
foreach (var member in members)
{
Trace.TraceInformation($"Id: {member.Key}, Name: {member.Value.Name}");
}
}
// MemberAdded event handler
void ChatMemberAdded(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has joined");
ListMembers(sender as GenericPresenceChannel<ChatMember>);
}
// MemberRemoved event handler
void ChatMemberRemoved(object sender, KeyValuePair<string, ChatMember> member)
{
Trace.TraceInformation($"Member {member.Value.Name} has left");
ListMembers(sender as GenericPresenceChannel<ChatMember>);
}
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
// Subscribe
try
{
GenericPresenceChannel<ChatMember> memberChannel =
await pusher.SubscribePresenceAsync<ChatMember>("presence-channel-1").ConfigureAwait(false);
memberChannel.MemberAdded += ChatMemberAdded;
memberChannel.MemberRemoved += ChatMemberRemoved;
Assert.AreEqual(true, memberChannel.IsSubscribed);
}
catch (ChannelUnauthorizedException)
{
// Handle client unauthorized error
}
catch (Exception)
{
// Handle other errors
}
The implementation of the HttpAuthorizer
class which provides the default implementation of an
IAuthorizer
has been modified to support the setting of an authentication header.
Here is an example of how to set the bearer token in an authentication header:
var authorizer = new HttpAuthorizer("https:/some.authorizer.com/auth")
{
AuthenticationHeader = new AuthenticationHeaderValue("Authorization", "Bearer noo6xaeN3cohYoozai4ar8doang7ai1elaeTh1di"),
};
var authToken = await authorizer.Authorize("private-test", "1234.9876");
If you require setting other headers you can override the PreAuthorize
method on the HttpAuthorizer
class.
public override void PreAuthorize(HttpClient httpClient)
{
base.PreAuthorize(httpClient);
// Add headers or other settings to the httpClient before authorizing.
}
The Subscribed
delegate is invoked when a channel is subscribed to. There are two different ways to specify a Subscribed event handler:
- Add an event handler using the
Pusher.Subscribed
delegate property. This event handler can be used to detect all channel subscriptions. - Provide an event handler as an input parameter to the
SubscribeAsync
orSubscribePresenceAsync
methods. This event handler is channel specific.
Detect all channel subscribed events using Pusher.Subscribed
// Lists all current presence channel members
void ListMembers(GenericPresenceChannel<ChatMember> channel)
{
Dictionary<string, ChatMember> members = channel.GetMembers();
foreach (var member in members)
{
Trace.TraceInformation($"Id: {member.Key}, Name: {member.Value.Name}");
}
}
// Subscribed event handler
void SubscribedHandler(object sender, Channel channel)
{
if (channel is GenericPresenceChannel<ChatMember> presenceChannel)
{
ListMembers(presenceChannel);
}
else if (channel.Name == "private-chat-channel-1")
{
// Trigger event
channel.Trigger("client-chat-event", new ChatMessage
{
Name = "Joe",
Message = "Hello from Joe!",
});
}
}
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Add subcribed event handler
pusher.Subscribed += SubscribedHandler;
// Create subscriptions
await pusher.SubscribeAsync("public-channel-1").ConfigureAwait(false);
await pusher.SubscribeAsync("private-chat-channel-1").ConfigureAwait(false);
await pusher.SubscribePresenceAsync<ChatMember>("presence-channel-1").ConfigureAwait(false);
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
Detect a subscribed event on a channel
// Lists all current presence channel members
void ListMembers(GenericPresenceChannel<ChatMember> channel)
{
Dictionary<string, ChatMember> members = channel.GetMembers();
foreach (var member in members)
{
Trace.TraceInformation($"Id: {member.Key}, Name: {member.Value.Name}");
}
}
// Presence channel subscribed event handler
void PresenceChannelSubscribed(object sender)
{
ListMembers(sender as GenericPresenceChannel<ChatMember>);
}
// Private channel subscribed event handler
void PrivateChannelSubscribed(object sender)
{
// Trigger event
((Channel)sender).Trigger("client-chat-event", new ChatMessage
{
Name = "Joe",
Message = "Hello from Joe!",
});
}
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Create subscriptions
await pusher.SubscribeAsync("public-channel-1").ConfigureAwait(false);
await pusher.SubscribeAsync("private-chat-channel-1", PrivateChannelSubscribed)
.ConfigureAwait(false);
await pusher.SubscribePresenceAsync<ChatMember>("presence-channel-1", PresenceChannelSubscribed)
.ConfigureAwait(false);
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
You can use UnsubscribeAsync
and UnsubscribeAllAsync
to remove subscriptions.
// Remove a channel subscription
await pusher.UnsubscribeAsync("public-channel-1").ConfigureAwait(false);
// Remove all channel subscriptions
await pusher.UnsubscribeAllAsync().ConfigureAwait(false);
Add this handler to recieve subscription count events. Read more about it here
void PusherCountEventHandler(object sender, string data) {
var dataAsObj = JsonConvert.DeserializeObject<SubscriptionCountData>(data);
Console.WriteLine(dataAsObj.subscriptionCount);
}
pusher.CountHandler += PusherCountEventHandler;
Allows you to send events to a user based on user id or terminating a user’s connections immediately. Read more about it here
The library provides an HttpUserAuthenticator
implementation of IUserAuthenticator
which makes an HTTP POST
request to an authenticating endpoint. However, you can implement your own authentication mechanism if required.
Setting up an authenticated user
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
UserAuthenticator = new HttpUserAuthenticator("https://some.authenticator.com/auth")
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Sign in
pusher.User.Signin();
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
await pusher.User.SigninDoneAsync();
The HttpUserAuthenticator
class supports the setting of an authentication header.
Here is an example of how to set the bearer token in an authentication header:
var authorizer = new HttpUserAuthenticator("https:/some.authenticator.com/auth")
{
AuthenticationHeader = new AuthenticationHeaderValue("Authorization", "Bearer noo6xaeN3cohYoozai4ar8doang7ai1elaeTh1di"),
};
var authToken = await authorizer.Authenticate("test-user", "1234.9876");
If you require setting other headers you can override the PreRequest
method on the HttpUserAuthenticator
class.
public override void PreRequest(HttpClient httpClient)
{
base.PreRequest(httpClient);
// Add headers or other settings to the httpClient before authorizing.
}
Events can be bound to at two levels; per-channel or globally.
The binding samples make use of the following classes
class ChatMember
{
public string Name { get; set; }
}
class ChatMessage : ChatMember
{
public string Message { get; set; }
}
These are bound to a specific channel, and mean that you can reuse event names in different parts of your client application.
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Channel event listener
void ChannelListener(PusherEvent eventData)
{
ChatMessage data = JsonConvert.DeserializeObject<ChatMessage>(eventData.Data);
Trace.TraceInformation($"Message from '{data.Name}': {data.Message}");
}
// Subscribe
Channel channel = await pusher.SubscribeAsync("private-chat-channel-1")
.ConfigureAwait(false);
// Bind event listener to channel
channel.Bind("client-chat-event", ChannelListener);
// Unbind event listener from channel
channel.Unbind("client-chat-event", ChannelListener);
// Unbind all "client-chat-event" event listeners from the channel
channel.Unbind("client-chat-event");
// Unbind all event listeners from the channel
channel.UnbindAll();
You can attach behavior to these events regardless of the channel the event is broadcast to.
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Global event listener
void GlobalListener(string eventName, PusherEvent eventData)
{
if (eventName == "client-chat-event")
{
ChatMessage data = JsonConvert.DeserializeObject<ChatMessage>(eventData.Data);
Trace.TraceInformation($"Message from '{data.Name}': {data.Message}");
}
}
// Bind global event listener
pusher.BindAll(GlobalListener);
// Unbind global event listener
pusher.Unbind(GlobalListener);
// Unbind all event listeners associated with the Pusher client
pusher.UnbindAll();
If you have signed in as an authenticated user, you can bind to watchlist events.
pusher.User.Watchlist.Bind("online", OnWatchlistOnlineEvent);
pusher.User.Watchlist.Bind("offline", OnWatchlistOfflineEvent);
void OnWatchlistOnlineEvent(WatchlistEvent watchlistEvent)
{
foreach (string userId in watchlistEvent.UserIDs)
{
Debug.Log($"UserID {userId} ONLINE");
}
}
void OnWatchlistOfflineEvent(WatchlistEvent watchlistEvent)
{
foreach (string userId in watchlistEvent.UserIDs)
{
Debug.Log($"UserID {userId} OFFLINE");
}
}
//Bind to all watchlist events
static void OnWatchlistEvent(string eventName, WatchlistEvent watchlistEvent)
{
foreach (var id in watchlistEvent.UserIDs)
{
Debug.Log($"{Environment.NewLine} OnWatchlistEvent {eventName} {watchlistEvent.Name} {id}");
}
}
Once a private or presence subscription has been authorized (see authenticating users) and the subscription has succeeded, it is possible to trigger events on those channels.
// Create client
Pusher pusher = new Pusher(Config.AppKey, new PusherOptions
{
Authorizer = new FakeAuthoriser(),
Cluster = Config.Cluster,
});
pusher.Error += ErrorHandler;
// Connect
await pusher.ConnectAsync().ConfigureAwait(false);
// Subscribe
Channel channel = await pusher.SubscribeAsync("private-chat-channel-1").ConfigureAwait(false);
// Trigger event
channel.Trigger("client-chat-event", new ChatMessage
{
Name = "Joe",
Message = "Hello from Joe!",
});
Events triggered by clients are called client events. Because they are being triggered from a client which may not be trusted there are a number of enforced rules when using them. Some of these rules include:
- Event names must have a
client-
prefix - Rate limits
- You can only trigger an event when the subscription has succeeded
For full details see the client events documentation.
The Pusher application settings are now loaded from a JSON config file stored in the root of the source tree and named AppConfig.test.json
. Make a copy of ./AppConfig.sample.json
and name it AppConfig.test.json
. Modify the contents of AppConfig.test.json
with your test application settings. All tests should pass. The AuthHost and ExampleApplication should also run without any start-up errors.
The majority of the tests are concurrency tests and the more the number of CPU(s) used the better. All tests should pass. However, some of the error code test paths fail intermittently when running on 2 CPU(s) - default build server configuration. With this in mind it is good to test on a 2 CPU configuration. A test settings file has been added to the root (CPU.count.2.runsettings) and you can specify it when running the tests via the menu option [Test]/[Configure Run Settings].
Also, a random latency is induced when authorizing a subscription. This is to weed out some of the concurrency issues. This adds to the time it takes to run all the tests. If you are running the tests often, you can speed things up by disabling the latency induction. Set the property EnableAuthorizationLatency
to false in AppConfig.test.json
.
Some of the tests have trace statements using System.Diagnostics.Trace
. One way to view them is to debug a test and open the Output\Debug window.
To generate a new signing key, open a PowerShell command console and execute the command
./StrongName/GeneratePusherKey.ps1
Copy the public key file PusherClient.public.snk
to the source root folder.
Take the base 64 encoded string and add it to the environment secret named CI_CODE_SIGN_KEY. This is used by publish.yml
. Once this step is done remove all traces of the private signing key file.
Also copy the PublicKey text and apply it to the code file ./PusherClient/Properties/AssemblyInfo.Signed.cs; for example
[assembly: InternalsVisibleTo("PusherClient.Tests, PublicKey=00240...8c1")]
[assembly: InternalsVisibleTo("PusherClient.Tests.Utilities, PublicKey=00240...8c1")]
You are encouraged to move to the Pusher Client SDK version 2. This major release includes a number of bug fixes and performance improvements. See the changelog for more information.
The following sections describe the changes in detail and describes how to update your code to the new version 2.x. If you run into problems you can always contact [email protected].
Previously the ConnectAsync
returned a ConnectionState
enum value after an async await. This is no longer the case; it returns void now. After the async await the state is always Connected
if the call succeeds. If the call fails an exception will be thrown.
Removed the public property ConcurrentDictionary<string, Channel> Channels
. Use the method GetAllChannels()
instead.
Removed the public static property TraceSource Trace
. Use PusherOptions.TraceLogger
instead.
Removed the public event delegate SubscriptionEventHandler Subscribed
. Use the optional input parameter SubscriptionEventHandler subscribedEventHandler
on Pusher.SubscribeAsync
and Pusher.SubscribePresenceAsync
instead. Alternatively, use Pusher.Subscribed
.
Removed the public property ConcurrentDictionary<string, T> Members
. Use GetMembers()
instead.
Six states remain simplifying the state change model:
- Uninitialized
- Connecting - Unimplemented state change in SDK version 1
- Connected - Unimplemented state change in SDK version 1
- Disconnecting
- Disconnected
- WaitingToReconnect
These states have been removed:
- Initialized
- NotConnected
- AlreadyConnected
- ConnectionFailed
- DisconnectionFailed
The signature of the MemberRemoved
delegate has changed from MemberRemovedEventHandler MemberRemoved
to MemberRemovedEventHandler<T> MemberRemoved
.
An optional parameter SubscriptionEventHandler subscribedEventHandler
has been added to the SubscribeAsync
and SubscribePresenceAsync<T>
methods.
/// <summary>
/// Fires when a channel becomes subscribed.
/// </summary>
public event SubscribedEventHandler Subscribed;
/// <summary>
/// Gets a channel.
/// </summary>
/// <param name="channelName">The name of the channel to get.</param>
/// <returns>The <see cref="Channel"/> if it exists; otherwise <c>null</c>.</returns>
public Channel GetChannel(string channelName)
{
// ...
}
/// <summary>
/// Get all current channels.
/// </summary>
/// <returns>A list of the current channels.</returns>
public IList<Channel> GetAllChannels()
{
// ...
}
/// <summary>
/// Removes a channel subscription.
/// </summary>
/// <param name="channelName">The name of the channel to unsubscribe.</param>
/// <returns>An awaitable task to use with async operations.</returns>
public async Task UnsubscribeAsync(string channelName)
{
// ...
}
/// <summary>
/// Removes all channel subscriptions.
/// </summary>
/// <returns>An awaitable task to use with async operations.</returns>
public async Task UnsubscribeAllAsync()
{
// ...
}
/// <summary>
/// Gets a member using the member's user ID.
/// </summary>
/// <param name="userId">The member's user ID.</param>
/// <returns>Retruns the member if found; otherwise returns null.</returns>
public T GetMember(string userId)
{
// ...
}
/// <summary>
/// Gets the current list of members as a <see cref="Dictionary{TKey, TValue}"/>
/// where the TKey is the user ID and TValue is the member detail.
/// </summary>
/// <returns>Returns a <see cref="Dictionary{TKey, TValue}"/> containing the current members.</returns>
public Dictionary<string, T> GetMembers()
{
// ...
}
Error codes less than 5000 remain the same. These are the error codes you can get from the Pusher server.
Error codes 5000 and above have been added for Client SDK detected errors. Almost all of these codes can be associated with a new exception class that derives from PusherException
.
This code is free to use under the terms of the MIT license.