Signalr Hubs API Guide - .Net Client (C#) - The ASP

8/10/2015
ASP.NETSignalRHubsAPIGuide.NETClient(C#)|TheASP.NETSite
ASP.NET SignalR Hubs API Guide .NET Client

C#
By Tom Dykstra and Patrick Fletcher | June 10, 2014 | Level 100 : Beginner
This document provides an introduction to using the Hubs API for SignalR version 2 in .NET clients, such as
Windows Store WinRT, WPF, Silverlight, and console applications.
The SignalR Hubs API enables you to make remote procedure calls RPCs from a server to connected clients
and from clients to the server. In server code, you define methods that can be called by clients, and you call
methods that run on the client. In client code, you define methods that can be called from the server, and you
call methods that run on the server. SignalR takes care of all of the clienttoserver plumbing for you.
SignalR also offers a lowerlevel API called Persistent Connections. For an introduction to SignalR, Hubs, and
Persistent Connections, or for a tutorial that shows how to build a complete SignalR application, see SignalR
Getting Started /signalr/overview/signalr20/gettingstartedwithsignalr20 .
Software versions used in this topic

Previous versions of this topic
Questions and comments
Overview
This document contains the following sections:
Client Setup #clientsetup
How to establish a connection #establishconnection
Crossdomain connections from Silverlight clients #slcrossdomain
How to configure the connection #configureconnection
How to set the maximum number of concurrent connections in WPF clients #maxconnections
How to specify query string parameters #querystring
How to specify the transport method #transport
How to specify HTTP headers #httpheaders
How to specify client certificates #clientcertificate
How to create the Hub proxy #proxy
How to define methods on the client that the server can call #callclient
Methods without parameters #clientmethodswithoutparms
Methods with parameters, specifying parameter types #clientmethodswithparmtypes
Methods with parameters, specifying dynamic objects for the parameters
#clientmethodswithdynamparms
How to remove a handler #removehandler

http://www.asp.net/signalr/overview/guidetotheapi/hubsapiguidenetclient
1/14
8/10/2015
How to call server methods from the client #callserver

How to handle connection lifetime events #connectionlifetime
How to handle errors #handleerrors
How to enable clientside logging #logging
WPF, Silverlight, and console application code samples for client methods that the server can call #wpfsl
For a sample .NET client projects, see the following resources:
gustavoarmenta / SignalRSamples https://github.com/gustavoarmenta/SignalRSamples on GitHub.com
WinRT, Silverlight, console app examples.
DamianEdwards / SignalRMoveShapeDemo / MoveShape.Desktop
https://github.com/DamianEdwards/SignalRMoveShapeDemo/tree/master/MoveShape/MoveShape.Desktop on
GitHub.com WPF example.

SignalR / Microsoft.AspNet.SignalR.Client.Samples
https://github.com/SignalR/SignalR/tree/master/samples/Microsoft.AspNet.SignalR.Client.Samples on
GitHub.com Console app example.

For documentation on how to program the server or JavaScript clients, see the following resources:
SignalR Hubs API Guide Server /signalr/overview/signalr20/hubsapi/hubsapiguideserver
SignalR Hubs API Guide JavaScript Client /signalr/overview/signalr20/hubsapi/hubsapiguidejavascript
client
Links to API Reference topics are to the .NET 4.5 version of the API. If you're using .NET 4, see the .NET 4 version of
the API topics http://msdn.microsoft.com/enus/library/jj891075v=vs.100.aspx .
Client setup
Install the Microsoft.AspNet.SignalR.Client http://nuget.org/packages/Microsoft.AspNet.SignalR.Client NuGet
package not the Microsoft.AspNet.SignalR http://nuget.org/packages/microsoft.aspnet.signalr package. This
package supports WinRT, Silverlight, WPF, console application, and Windows Phone clients, for both .NET 4 and .NET
4.5.
If the version of SignalR that you have on the client is different from the version that you have on the server, SignalR
is often able to adapt to the difference. For example, a server running SignalR version 2 will support clients that have
1.1.x installed as well as clients that have version 2 installed. If the difference between the version on the server and
the version on the client is too great, or if the client is newer than the server, SignalR throws an
InvalidOperationException exception when the client tries to establish a connection. The error message is "You
areusingaversionoftheclientthatisn'tcompatiblewiththeserver.ClientversionX.X,
serverversionX.X".
How to establish a connection

Before you can establish a connection, you have to create a HubConnection object and create a proxy. To establish
the connection, call the Start method on the HubConnection object.
varhubConnection=newHubConnection("http://www.contoso.com/");
IHubProxystockTickerHubProxy=hubConnection.CreateHubProxy("StockTickerHub");
stockTickerHubProxy.On<Stock>("UpdateStockPrice",stock=>Console.WriteLine("Stockupdate
2/14
8/10/2015
for{0}newprice{1}",stock.Symbol,stock.Price));
awaithubConnection.Start();
Note: For JavaScript clients you have to register at least one event handler before calling the
Start method to establish the connection. This is not necessary for .NET clients. For JavaScript
clients, the generated proxy code automatically creates proxies for all Hubs that exist on the
server, and registering a handler is how you indicate which Hubs your client intends to use. But
for a .NET client you create Hub proxies manually, so SignalR assumes that you will be using any
Hub that you create a proxy for.
The sample code uses the default "/signalr" URL to connect to your SignalR service. For information about how to
specify a different base URL, see ASP.NET SignalR Hubs API Guide Server The /signalr URL
/signalr/overview/signalr20/hubsapi/hubsapiguideserver#signalrurl .
The Start method executes asynchronously. To make sure that subsequent lines of code don't execute until after the
connection is established, use await in an ASP.NET 4.5 asynchronous method or .Wait() in a synchronous method.
Don't use .Wait() in a WinRT client.
awaitconnection.Start();
connection.Start().Wait();
The HubConnection class is threadsafe.
Crossdomain connections from Silverlight clients

For information about how to enable crossdomain connections from Silverlight clients, see Making a Service
Available Across Domain Boundaries http://msdn.microsoft.com/enus/library/cc197955v=vs.95.aspx .
How to configure the connection

Before you establish a connection, you can specify any of the following options:
Concurrent connections limit.
Query string parameters.
The transport method.
HTTP headers.
Client certificates.
How to set the maximum number of concurrent connections in WPF clients

In WPF clients, you might have to increase the maximum number of concurrent connections from its default value of
2. The recommended value is 10.
3/14
8/10/2015
ServicePointManager.DefaultConnectionLimit=10;
For more information, see ServicePointManager.DefaultConnectionLimit http://msdn.microsoft.com/en

us/library/system.net.servicepointmanager.defaultconnectionlimit.aspx .
How to specify query string parameters

If you want to send data to the server when the client connects, you can add query string parameters to the
connection object. The following example shows how to set a query string parameter in client code.
varquerystringData=newDictionary<string,string>();
querystringData.Add("contosochatversion","1.0");
varconnection=newHubConnection("http://contoso.com/",querystringData);
The following example shows how to read a query string parameter in server code.
publicclassStockTickerHub:Hub
{
publicoverrideTaskOnConnected()
{
varversion=Context.QueryString["contosochatversion"];
if(version!="1.0")
{
Clients.Caller.notifyWrongVersion();
}
returnbase.OnConnected();
}
}
How to specify the transport method

As part of the process of connecting, a SignalR client normally negotiates with the server to determine the best
transport that is supported by both server and client. If you already know which transport you want to use, you can
bypass this negotiation process. To specify the transport method, pass in a transport object to the Start method. The
following example shows how to specify the transport method in client code.
awaithubConnection.Start(newLongPollingTransport());
4/14
8/10/2015
The Microsoft.AspNet.SignalR.Client.Transports http://msdn.microsoft.com/enus/library/jj918090v=vs.111.aspx

namespace includes the following classes that you can use to specify the transport.
LongPollingTransport http://msdn.microsoft.com/en
us/library/microsoft.aspnet.signalr.client.transports.longpollingtransportv=vs.111.aspx
ServerSentEventsTransport http://msdn.microsoft.com/en
us/library/microsoft.aspnet.signalr.client.transports.serversenteventstransportv=vs.111.aspx
WebSocketTransport http://msdn.microsoft.com/en
us/library/microsoft.aspnet.signalr.client.transports.websockettransportv=vs.111.aspx Available only when both
server and client use .NET 4.5.

AutoTransport http://msdn.microsoft.com/en
us/library/microsoft.aspnet.signalr.client.transports.autotransportv=vs.111.aspx Automatically chooses the best
transport that is supported by both the client and the server. This is the default transport. Passing this in to the
Start method has the same effect as not passing in anything.
The ForeverFrame transport is not included in this list because it is used only by browsers.
For information about how to check the transport method in server code, see ASP.NET SignalR Hubs API Guide
Server How to get information about the client from the Context property /signalr/overview/signalr20/hubs
api/hubsapiguideserver#contextproperty . For more information about transports and fallbacks, see Introduction
to SignalR Transports and Fallbacks /signalr/overview/signalr20/gettingstartedwithsignalr20/introductionto
signalr#transports .
How to specify HTTP headers

To set HTTP headers, use the Headers property on the connection object. The following example shows how to add
an HTTP header.
hubConnection=newhubConnection("http://www.contoso.com/");
connection.Headers.Add("headername","headervalue");
How to specify client certificates

To add client certificates, use the AddClientCertificate method on the connection object.
hubConnection=newhubConnection("http://www.contoso.com/");
hubConnection.AddClientCertificate(X509Certificate.CreateFromCertFile("MyCert.cer"));
How to create the Hub proxy

5/14
8/10/2015
In order to define methods on the client that a Hub can call from the server, and to invoke methods on a Hub at the
server, create a proxy for the Hub by calling CreateHubProxy on the connection object. The string you pass in to
CreateHubProxy is the name of your Hub class, or the name specified by the HubName attribute if one was used on
the server. Name matching is caseinsensitive.
Hub class on server
Create client proxy for the Hub class

If you decorate your Hub class with a HubName attribute, use that name.
Hub class on server
[HubName("stockTicker")]
Create client proxy for the Hub class

IHubProxystockTickerHubProxy=hubConnection.CreateHubProxy("stockTicker");
stockTickerHubProxy.On<Stock>("UpdateStockPrice",stock=>
Console.WriteLine("Stockupdatefor{0}newprice{1}",stock.Symbol,stock.Price));
The proxy object is threadsafe. In fact, if you call HubConnection.CreateHubProxy multiple times with the same
hubName, you get the same cached IHubProxy object.
How to define methods on the client that the server can call
To define a method that the server can call, use the proxy's On method to register an event handler.
Method name matching is caseinsensitive. For example, Clients.All.UpdateStockPrice on the server will
execute updateStockPrice, updatestockprice, or UpdateStockPrice on the client.
Different client platforms have different requirements for how you write method code to update the UI. The examples
shown are for WinRT Windows Store .NET clients. WPF, Silverlight, and console application examples are provided in
a separate section later in this topic #wpfsl .
6/14
8/10/2015
Methods without parameters

If the method you're handling does not have parameters, use the nongeneric overload of the On method:
Server code calling client method without parameters
{
publicvoidNotifyAllClients()
{
Clients.All.Notify();
}
}
WinRT Client code for method called from server without parameters see WPF and Silverlight examples later
in this topic #wpfsl
stockTickerHub.On("notify",()=>
//ContextisareferencetoSynchronizationContext.Current
Context.Post(delegate
{
textBox.Text+="Notified!\n";
},null)
);
Methods with parameters, specifying the parameter types

If the method you're handling has parameters, specify the types of the parameters as the generic types of the On
method. There are generic overloads of the On method to enable you to specify up to 8 parameters 4 on Windows
Phone 7. In the following example, one parameter is sent to the UpdateStockPrice method.
Server code calling client method with a parameter
publicvoidBroadcastStockPrice(Stockstock)
{
context.Clients.Others.UpdateStockPrice(stock);
}
The Stock class used for the parameter

publicclassStock
{
publicstringSymbol{get;set;}
publicdecimalPrice{get;set;}
7/14
8/10/2015
WinRT Client code for a method called from server with a parameter see WPF and Silverlight examples later
in this topic #wpfsl
{
textBox.Text+=string.Format("Stockupdatefor{0}newprice{1}\n",stock.Symbol,
stock.Price);
},null)
);

As an alternative to specifying parameters as generic types of the On method, you can specify parameters as dynamic
objects:
Server code calling client method with a parameter
publicvoidBroadcastStockPrice(Stockstock)
{
context.Clients.Others.UpdateStockPrice(stock);
}
The Stock class used for the parameter

publicclassStock
{
}
WinRT Client code for a method called from server with a parameter, using a dynamic object for the
parameter see WPF and Silverlight examples later in this topic #wpfsl
stockTickerHubProxy.On("UpdateStockPrice",stock=>
{
stock.Price);
},null)
);
8/14
8/10/2015
How to remove a handler

To remove a handler, call its Dispose method.
Client code for a method called from server
varupdateStockPriceHandler=stockTickerHubProxy.On<Stock>("UpdateStockPrice",stock=>
{
stock.Price);
},null)
);
Client code to remove the handler

updateStockPriceHandler.Dispose();
How to call server methods from the client

To call a method on the server, use the Invoke method on the Hub proxy.
If the server method has no return value, use the nongeneric overload of the Invoke method.
Server code for a method that has no return value
{
publicvoidJoinGroup(stringgroupName)
{
Groups.Add(Context.ConnectionId,groupName);
}
}
Client code calling a method that has no return value

stockTickerHubProxy.Invoke("JoinGroup","SignalRChatRoom");
If the server method has a return value, specify the return type as the generic type of the Invoke method.
Server code for a method that has a return value and takes a complex type parameter
publicIEnumerable<Stock>AddStock(Stockstock)
{
_stockTicker.AddStock(stock);
9/14
8/10/2015
return_stockTicker.GetAllStocks();
}
The Stock class used for the parameter and return value
publicclassStock
{
}
Client code calling a method that has a return value and takes a complex type parameter, in an ASP.NET 4.5
async method
varstocks=awaitstockTickerHub.Invoke<IEnumerable<Stock>>("AddStock",newStock(){
Symbol="MSFT"});
foreach(Stockstockinstocks)
{
textBox.Text+=string.Format("Symbol:{0}price:{1}\n",stock.Symbol,stock.Price);
}
Client code calling a method that has a return value and takes a complex type parameter, in a synchronous
method
varstocks=stockTickerHub.Invoke<IEnumerable<Stock>>("AddStock",newStock(){Symbol=
"MSFT"}).Result;
{
textBox.Text+=string.Format("Symbol:{0}price:{1}\n",stock.Symbol,stock.Price);
}
The Invoke method executes asynchronously and returns a Task object. If you don't specify await or .Wait(), the
next line of code will execute before the method that you invoke has finished executing.
How to handle connection lifetime events

SignalR provides the following connection lifetime events that you can handle:
Received: Raised when any data is received on the connection. Provides the received data.
ConnectionSlow: Raised when the client detects a slow or frequently dropping connection.
Reconnecting: Raised when the underlying transport begins reconnecting.
Reconnected: Raised when the underlying transport has reconnected.
StateChanged: Raised when the connection state changes. Provides the old state and the new state. For
information about connection state values see ConnectionState Enumeration http://msdn.microsoft.com/en
10/14
8/10/2015
us/library/microsoft.aspnet.signalr.client.connectionstatev=vs.111.aspx .
Closed: Raised when the connection has disconnected.

For example, if you want to display warning messages for errors that are not fatal but cause intermittent connection
problems, such as slowness or frequent dropping of the connection, handle the ConnectionSlow event.
hubConnection.ConnectionSlow+=()=>Console.WriteLine("Connectionproblems.");
For more information, see Understanding and Handling Connection Lifetime Events in SignalR
/signalr/overview/signalr20/hubsapi/handlingconnectionlifetimeevents .
How to handle errors

If you don't explicitly enable detailed error messages on the server, the exception object that SignalR returns after an
error contains minimal information about the error. For example, if a call to newContosoChatMessage fails, the error
message in the error object contains "TherewasanerrorinvokingHubmethod
'contosoChatHub.newContosoChatMessage'." Sending detailed error messages to clients in production is not
recommended for security reasons, but if you want to enable detailed error messages for troubleshooting purposes,
use the following code on the server.
varhubConfiguration=newHubConfiguration(http://msdn.microsoft.com/en
us/library/microsoft.aspnet.signalr.hubconfiguration(v=vs.111).aspx)();
hubConfiguration.EnableDetailedErrors=true;
App.MapSignalR(hubConfiguration);
To handle errors that SignalR raises, you can add a handler for the Error event on the connection object.
hubConnection.Error+=ex=>Console.WriteLine("SignalRerror:{0}",ex.Message);
To handle errors from method invocations, wrap the code in a trycatch block.
try
{
IEnumerable<Stock>stocks=awaitstockTickerHub.Invoke<IEnumerable<Stock>>
("GetAllStocks");
{
Console.WriteLine("Symbol:{0}price:{1}",stock.Symbol,stock.Price);
}
}
catch(Exceptionex)
{
Console.WriteLine("ErrorinvokingGetAllStocks:{0}",ex.Message);
}
11/14
8/10/2015
How to enable clientside logging

To enable clientside logging, set the TraceLevel and TraceWriter properties on the connection object.
hubConnection.TraceLevel=TraceLevels.All;
hubConnection.TraceWriter=Console.Out;
WPF, Silverlight, and console application code samples for client methods
that the server can call
The code samples shown earlier for defining client methods that the server can call apply to WinRT clients. The
following samples show the equivalent code for WPF, Silverlight, and console application clients.
Methods without parameters

WPF client code for method called from server without parameters
stockTickerHub.On<Stock>("notify",()=>
Dispatcher.InvokeAsync(()=>
{
SignalRTextBlock.Text+=string.Format("Notified!");
})
);
Silverlight client code for method called from server without parameters
stockTickerHub.On<Stock>("notify",()=>
{
textBox.Text+="Notified!";
},null)
);
Console application client code for method called from server without parameters
stockTickerHubProxyProxy.On("Notify",()=>Console.WriteLine("Notified!"));
Methods with parameters, specifying the parameter types

WPF client code for a method called from server with a parameter
12/14
8/10/2015
{
textBox.Text+=string.Format("Stockupdatefor{0}newprice{1}\n",
stock.Symbol,stock.Price);
})
);
Silverlight client code for a method called from server with a parameter
{
stock.Price);
},null)
);
Console application client code for a method called from server with a parameter
Console.WriteLine("Symbol{0}Price{1}",stock.Symbol,stock.Price));

WPF client code for a method called from server with a parameter, using a dynamic object for the parameter
{
textBox.Text+=string.Format("Stockupdatefor{0}newprice{1}\n",
stock.Symbol,stock.Price);
})
);
Silverlight client code for a method called from server with a parameter, using a dynamic object for the
parameter
{
stock.Price);
13/14
8/10/2015
},null)
);
Console application client code for a method called from server with a parameter, using a dynamic object for
the parameter
Console.WriteLine("Symbol{0}Price{1}",stock.Symbol,stock.Price));
This article was originally created on June 10, 2014
Author Information
Tom DykstraTom Dykstra is a Senior Programming Writer on Microsoft's Web Platform &
Tools Content Team...
Patrick FletcherPatrick Fletcher is a former programmerwriter on the ASP.NET team.
Comments 9
This site is managed for Microsoft by Neudesic, LLC. | 2015 Microsoft. All rights reserved.
14/14

Signalr Hubs API Guide - .Net Client (C#) - The ASP

Uploaded by

Copyright:

Available Formats

Signalr Hubs API Guide - .Net Client (C#) - The ASP

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Signalr Hubs API Guide - .Net Client (C#) - The ASP

Uploaded by

Copyright:

Available Formats

8/10/2015

ASP.NET SignalR Hubs API Guide .NET Client

Software versions used in this topic

How to remove a handler #removehandler

How to call server methods from the client #callserver

GitHub.com WPF example.

GitHub.com Console app example.

How to establish a connection

The HubConnection class is threadsafe.

Crossdomain connections from Silverlight clients

How to configure the connection

How to set the maximum number of concurrent connections in WPF clients

For more information, see ServicePointManager.DefaultConnectionLimit http://msdn.microsoft.com/en

How to specify query string parameters

How to specify the transport method

The Microsoft.AspNet.SignalR.Client.Transports http://msdn.microsoft.com/enus/library/jj918090v=vs.111.aspx

server and client use .NET 4.5.

How to specify HTTP headers

How to specify client certificates

How to create the Hub proxy

Create client proxy for the Hub class

Create client proxy for the Hub class

Methods without parameters

Methods with parameters, specifying the parameter types

The Stock class used for the parameter

Methods with parameters, specifying dynamic objects for the parameters

The Stock class used for the parameter

How to remove a handler

Client code to remove the handler

How to call server methods from the client

Client code calling a method that has no return value

How to handle connection lifetime events

Closed: Raised when the connection has disconnected.

How to handle errors

How to enable clientside logging

Methods without parameters

Methods with parameters, specifying the parameter types

Methods with parameters, specifying dynamic objects for the parameters

This article was originally created on June 10, 2014

Patrick FletcherPatrick Fletcher is a former programmerwriter on the ASP.NET team.

You might also like