C#PubNub Network Lifecycle for C# V4


These docs are for PubNub 4.0 for C# which is our latest and greatest! For the docs of the 3.x versions of the SDK, please check the links: C#, Windows 8, Windows 8.1, ASP.Net, Windows Phone 8, Windows Phone 8.1, Xamarin.iOS, Xamarin.Android, Xamarin.Mac and C# PCL.

If you have questions about the PubNub for C# SDK, please contact us at support@pubnub.com.

It is users responsibility to prepare client's configuration instance and pass it during PubNub client instantiation. As long as there is a reference to the client instance it will be alive. The initialized client doesn't perform any activities until activated by user commands.

Client doesn't check for active connection on its own and instead relies on network API/library response.

On a user command, the client prepares a REST request to PubNub API and passes it to the networking API/library for processing. If there were no issues and the response arrived in time, the results are parsed and wrapped into objects which are returned using callbacks.

If there was an issue during request processing, networking API will return information about the error which will then be parsed and wrapped into objects and returned to the caller.

In case of network issues, Realtime API's will return status object with category set to PNNetworkIssuesCategory.

There are also a set of other error categories:

PNNetworkIssuesCategory - (in case there was no connection at the moment when the client tried to send request. Other .net web exceptions are ConnectFailure, SendFailure, SecureChannelFailure, NameResolutionFailure, SocketException).

PNAccessDeniedCategory - Access Manager issues and in most cases because of not enabling PAM or GMT timezone mismatch or supplying invalid subscribe/publish/secret keys.

PNBadRequestCategory - required data is missing while sending request. Cases like too long message publishing, invalid timestamp, invalid json, subscribing empty channelgroup.

PNConnectedCategory - when the channel is subscribed successfully.

PNDisconnectedCategory - when the subscribed channel is unsubscribed successfully.

Heartbeat API can be used as a way to detect when network issues appear. Heartbeats send a request at intervals (which is set during client instance configuration) and utilize observer's callback to report successful and failed attempts. There is a chance that the network will get spotty between calls to this API and the socket with active long-poll (subscribe API for realtime messages) may not notice those issues and listen for events from a broken pipe.

There are two status events which may tell what there is some network issues: PNNetworkIssuesCategory and PNReconnectedCategory. C# V4 has exclusive statuses that can reveal deeper information about the network from the .net API's.

Network connection issue at the moment when request has been sent. This status is returned immediately to calling API through callback.

When the connect is lost, C# SDK attempts to check, if network is available. After reconnect attempt, status will sent through callback whether ok or not.

There are some unknown errors which occasionally occurs based on the specific device or environment. These errors were categorised here. However the PNStatus hold lot of information for troubleshooting purposes.

There is PNReconnectedCategory which can be generated in the middle of client lifecycle while it subscribed to real-time data channels.

In case that this status arrives, client starts pinging PubNub services using Time API every 10 seconds. As soon as a request is processed successfully, client will try to restore subscription on channels on which it was subscribed previously. If configured to keep timetoken on subscription restore, client will try to catch up on missed messages.

When client completes subscription restore after PNReconnectedCategory with status code 200, it will notify observers what client has been reconnected to real-time data channels.

If more than 100 messages will arrive (from PubNub in-memory messages cache), it is better to use history API to fetch potentially missed messages. To be notified about this case, requestMessageCountThreshold should be set to 100 - this will tell client to send PNRequestMessageCountExceededCategory status.

The C# V4 platform ships with reconnection policy disabled by default and can be enabled by setting ReconnectionPolicy on PNConfiguration to one of the following values:

  1. (default) PNReconnectionPolicy.NONE - indicates that NO action will taken when there is a network or internet issue.
  2. PNReconnectionPolicy.LINEAR - SDK will try to reconnect each 3 seconds.
  3. PNReconnectionPolicy.EXPONENTIAL - SDK uses the Exponential Backoff algorithm to reconnect when there is a network or internet issue. SDK uses MINEXPONENTIALBACKOFF = 1 second and MAXEXPONENTIALBACKOFF = 32 seconds. See: https://en.wikipedia.org/wiki/Exponential_backoff for more details.

On some platforms, application owners have more visibility into networking conditions than the SDK. You can call pubnub.Disconnect() when network issues are identified and call pubnub.Reconnect() on each of the SDKs to force the SDK to disconnect and try and reach out PubNub.

403 response on a subscribe event occurs when Access Manager is enabled and the user doesn't have access to the channel or the grant TTL has expired. In this case you need to create a new auth key, grant access to the user (from your server) and subscribe again.

For more info please check: http://www.pubnub.com/docs/c-sharp-dot-net-c-sharp/pam-security#handling-permission-denied-errors