Connecting with WebSockets (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Send and receive data using WebSockets for low-latency, secure, real-time bi-directional network communication using features in the Windows.Networking.Sockets namespace.

What are WebSockets?

The WebSocket Protocol defines a mechanism for fast, secure two-way communication between a client and a server over the web. Data is transferred immediately over a full-duplex single socket connection, allowing messages to be sent and received from both endpoints in real time. WebSockets are ideal for use in Windows Runtime apps that include real-time gaming, instant social network notifications, up-to-date displays of stock or weather information, and other apps requiring secure and fast data transfer. WebSockets also work through proxies and firewalls since the WebSocket Protocol by default uses the same ports used by web browsers (HTTP and HTTPS).

To establish a WebSocket connection, a specific, HTTP-based handshake is exchanged between the client and the server. If successful, the application-layer protocol is "upgraded" from HTTP to WebSockets, using the previously established TCP connection. Once this occurs, HTTP is completely out of the picture; data can be sent or received using the WebSocket protocol by both endpoints until the WebSocket connection is closed.

Important A client cannot use WebSockets to transfer data unless the server also uses the WebSocket protocol. If the server does not support WebSockets, you must use another method of data transfer.

The Windows.Networking.Sockets namespace provides support for client WebSockets in the Windows Runtime. Support for both client and server WebSockets is supported on Windows 8.1 for desktop apps.

The Windows.Networking.Sockets namespace defines two types of WebSocket objects for use by clients in Windows Runtime apps: MessageWebSocket and StreamWebSocket. The table below describes the two types of WebSockets.

MessageWebSocket	StreamWebSocket
Suitable for typical scenarios where messages are not extremely large.	Suitable for scenarios in which large files (such as photos or movies) are being transferred.
Enables notification that an entire WebSocket message has been received.	Allows sections of a message to be read with each read operation.
Supports both UTF-8 and binary messages.	Supports only binary messages.
Somewhat comparable to a UDP socket (DatagramSocket).	Somewhat comparable to a TCP socket (StreamSocket).

Using WebSockets with network isolation

The network isolation feature in the Windows Runtime enables a developer to control and limit network access by a Windows Runtime app. Not all apps may require access to the network. However for those apps that do, Windows Runtime provides different levels of access to the network that can be enabled by selecting appropriate capabilities.

Network isolation allows a developer to define for each app the scope of required network access. An app without the appropriate scope defined is prevented from accessing the specified type of network, and specific type of network request (outbound client-initiated requests or both inbound unsolicited requests and outbound client-initiated requests). The ability to set and enforce network isolation ensures that if an app does get compromised, it can only access networks where the app has explicitly been granted access. This significantly reduces the scope of the impact on other applications and on Windows.

Network isolation affects any class elements in the Windows.Networking.Sockets namespace that try to access the network. Windows actively enforces network isolation. A call to a method on the MessageWebSocket or StreamWebSocket class in the Windows.Networking.Sockets namespace that results in network access may fail because of network isolation if the appropriate network capability has not been enabled.

The network capabilities for an app are configured in the app manifest when the app is built. Network capabilities are usually added using Microsoft Visual Studio 2013 Update 2 when developing the app. Network capabilities may also be set manually in the app manifest file using a text editor.

For more detailed information on network isolation, see the How to set network capabilities.

Developer audience

The examples in the following topics use JavaScript and are based on the WebSocket sample. For general help creating a Windows Runtime app using JavaScript, see Roadmap for Windows Runtime apps using JavaScript using JavaScript.

In this section

Topic	Description
How to connect with a MessageWebSocket	Details the requirements and specific steps for using a MessageWebSocket to send and receive data from a web server.
How to connect with a StreamWebSocket	Details the requirements and specific steps for using a StreamWebSocket to send and receive data from a web server.
How to use advanced WebSocket controls	Explains how to use advanced socket controls to set options on a WebSocket object.
How to secure WebSocket connections with TLS/SSL	Explains how to secure WebSocket connections with Transport Layer Security (TLS)/Secure Sockets Layer (SSL).

Section	Description
How to configure network isolation capabilities	Explains the network isolation feature and how to configure network isolation capabilities to fully control network access for a Windows Store app.
Making network connections with sockets	Details the requirements and specific steps for using sockets to send and receive data from a network resource.
Adding support for networking	Contains information on adding support for networking to your app.
Troubleshoot and debug network connections	Provides suggestions and information to help troubleshoot connection issues.