title: "ASP.NET SignalR Hubs API Guide - .NET Client (SignalR 1.x) | Microsoft Docs"
author: pfletcher
description: "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 cons..."
ASP.NET SignalR Hubs API Guide - .NET Client (SignalR 1.x)
====================
by [Patrick Fletcher](https://github.com/pfletcher), [Tom Dykstra](https://github.com/tdykstra)
> 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 client-to-server plumbing for you.
>
> SignalR also offers a lower-level 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](../getting-started/index.md).
## Overview
This document contains the following sections:
- [Client Setup](#clientsetup)
- [How to establish a connection](#establishconnection)
- [Cross-domain 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)
- [How to call server methods from the client](#callserver)
- [How to handle connection lifetime events](#connectionlifetime)
- [How to handle errors](#handleerrors)
- [How to enable client-side 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:
- [DamianEdwards / SignalR-MoveShapeDemo / MoveShape.Desktop](https://github.com/DamianEdwards/SignalR-MoveShapeDemo/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](../guide-to-the-api/hubs-api-guide-server.md)
- [SignalR Hubs API Guide - JavaScript Client](../guide-to-the-api/hubs-api-guide-javascript-client.md)
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](https://msdn.microsoft.com/en-us/library/jj891075(v=vs.100).aspx).
<aid="clientsetup"></a>
## 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, when SignalR version 2.0 is released and you install that on the server, the server will support clients that have 1.1.x installed as well as clients that have 2.0 installed. If the difference between the version on the server and the version on the client is too great, SignalR throws an `InvalidOperationException` exception when the client tries to establish a connection. The error message is "`You are using a version of the client that isn't compatible with the server. Client version X.X, server version X.X`".
<aid="establishconnection"></a>
## 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.
> 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](../guide-to-the-api/hubs-api-guide-server.md).
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.
### Cross-domain connections from Silverlight clients
For information about how to enable cross-domain connections from Silverlight clients, see [Making a Service Available Across Domain Boundaries](https://msdn.microsoft.com/en-us/library/cc197955(v=vs.95).aspx).
<aid="configureconnection"></a>
## 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.
<aid="maxconnections"></a>
### 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.
For more information, see [ServicePointManager.DefaultConnectionLimit](https://msdn.microsoft.com/en-us/library/system.net.servicepointmanager.defaultconnectionlimit.aspx).
<aid="querystring"></a>
### 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.
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.
The [Microsoft.AspNet.SignalR.Client.Transports](https://msdn.microsoft.com/en-us/library/jj918090(v=vs.111).aspx) namespace includes the following classes that you can use to specify the transport.
- [WebSocketTransport](https://msdn.microsoft.com/en-us/library/microsoft.aspnet.signalr.client.transports.websockettransport(v=vs.111).aspx) (Available only when both server and client use .NET 4.5.)
- [AutoTransport](https://msdn.microsoft.com/en-us/library/microsoft.aspnet.signalr.client.transports.autotransport(v=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](../guide-to-the-api/hubs-api-guide-server.md). For more information about transports and fallbacks, see [Introduction to SignalR - Transports and Fallbacks](../getting-started/introduction-to-signalr.md#transports).
<aid="httpheaders"></a>
### 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.
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 case-insensitive.
The proxy object is thread-safe. In fact, if you call `HubConnection.CreateHubProxy` multiple times with the same `hubName`, you get the same cached `IHubProxy` object.
<aid="callclient"></a>
## 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 case-insensitive. 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).
<aid="clientmethodswithoutparms"></a>
### Methods without parameters
If the method you're handling does not have parameters, use the non-generic overload of the `On` method:
**Server code calling client method without parameters**
### 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**
**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))**
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.
<aid="connectionlifetime"></a>
## 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](https://msdn.microsoft.com/en-us/library/microsoft.aspnet.signalr.client.connectionstate(v=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.
For more information, see [Understanding and Handling Connection Lifetime Events in SignalR](../guide-to-the-api/handling-connection-lifetime-events.md).
<aid="handleerrors"></a>
## 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 "`There was an error invoking Hub method '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.
## 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**
