The sample shows how to use the ControlChannelTrigger class to enable a Windows Store app using a StreamWebSocket to be always connected and always reachable. This sample demonstrates the use of background network notifications in a Windows Store app.

The ControlChannelTrigger class and related interfaces are used to enable real-time network status and triggers for class elements in the Windows.Networking.Sockets and related namespaces. These features allow an app to receive notifications while the app is suspended. These notifications can be set to occur when network packets are received or to maintain keep-alive packets. This sample uses notifications to receive incoming network packets and maintain keep-alive packets. This allows the app to minimize power usage for improved battery life and wake up to respond to incoming packets and other conditions only when needed.

The ControlChannelTrigger class is commonly used by long-running network apps to minimize network and system resource usage (an email app that is left running, for example). Network triggers allow an app to drop to a low-power mode for periods of time while still keeping established network connections intact and operating in a low-power state. An app can set a server keep-alive interval used by the system for when the app should wake up. An app can also set a trigger to wake up when network data is received by the system for the app.

A Windows Store app for Windows 8.1 is normally suspended when it is no longer in the foreground app and moved to the background. There are some exceptions to suspending an app (actively printing, accessing an audio stream, and transferring files in the background, for example). The ControlChannelTrigger class allows a network app that has established a TCP connection to notify the system that an established network connection should be kept operational and the system should wake up the suspended app when network data is received for the app or the server keep-alive timer interval expires.

In this sample, the ControlChannelTrigger class is used with the StreamWebSocket class to connect to web server that supports WebSockets. However, the ControlChannelTrigger class can also be used with other network transports that establish a TCP connection.

The ControlChannelTrigger class can be used with instances of the following classes in the Windows.Networking.Sockets that establish a TCP connection.

The ControlChannelTrigger class can also be used by instances of the following that establish a TCP connection:

Note  The ControlChannelTrigger class is not supported in a Windows Store app built for Windows using JavaScript.

Versions of this sample are provided in both C# and C++. This sample requires some experience with network programming.

This sample requires the following capabilities:

To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.

To obtain an evaluation copy of Microsoft Visual Studio 2013, go to Visual Studio 2013.

Note  For Windows 8 app samples, download the Windows 8 app samples pack. The samples in the Windows 8 app samples pack will build and run only on Microsoft Visual Studio 2012.

Related topics

Other resources
Adding support for networking
Connecting to a WebSocket service
How to configure network isolation capabilities
How to set background connectivity options
Supporting your app with background tasks
Reference
ControlChannelTrigger
StreamWebSocket
Windows.Networking.Sockets
Samples
ControlChannelTrigger HttpClient sample
ControlChannelTrigger IXMLHTTPRequest2 sample
ControlChannelTrigger StreamSocket sample
Connecting with WebSockets sample
Windows 8 app samples

Operating system requirements

Client
Windows 8.1
Server
Windows Server 2012 R2

Build the sample

  1. Start Visual Studio 2013 and select File > Open > Project/Solution.
  2. Go to the directory in which you unzipped the sample. Go to the directory named for the sample, and double-click the Visual Studio 2013 Solution (.sln) file.
  3. Press F7 or use Build > Build Solution to build the sample.

Run the sample

This sample requires that a web server that supports WebSockets is available on a separate computer for the app to access for sending requests and receiving responses. The web server must be started before the app is run. The web server must also have a WebSocketSample path available for the EchoWebSocket.ashx file. The sample includes a PowerShell script that will install IIS on a computer, create the WebSocketSample folder on the server, and copy files to this folder.

The easiest way to run the sample is to use the provided web server scripts. Browse to the Server folder in your sample folder to setup and start the web server. Copy this folder and its subfolder to another computer and run the server scripts. There are two options possible.

When the web server is not needed anymore, please browse to the copy of the Server folder on the computer and run one of the following:

To configure the app for use with the web server:

The sample can run using any web server, not only the one provided with the sample. In this case, running the previous scripts is not required. However, this requires some special configuration of the server to create the Server folder and copy files to this folder.

To configure for use with a different web server:

Copy the Server\webSite directory to the WebSocketSample folder on the web server and configure the server to support WebSockets. Also configure the web server so it delays responses by about 25 seconds. This delay is to ensure the client app can have enough time to enter suspended state and then receive the incoming response from the server.
Revise or replace the EchoWebSocket.ashx file as need so it works with the web server.

Note  IIS is not available on ARM builds. Instead, set up the web server on a separate 64-bit or x86 32-bit computer.

Note  When used with the supplied scripts, this Windows Store app sample communicates with another process (IIS server which is a desktop app) on the same machine over loopback for demonstration purposes only. A Windows Store app that communicates over loopback to another process that represents a Windows Store app is not allowed and such apps will not pass Store validation. For more information, see How to configure network isolation capabilities.

To deploy this app after building it, select Deploy Solution from the Build menu. A tile for the sample will be available on the Start Screen. To both deploy and run the sample, press F5 (run with debugging enabled) or Ctrl+F5 (run without debugging enabled) from Visual Studio 2013 (any SKU). (Or select the corresponding options from the Debug menu.)

After the server computer has started, start the app on the local computer.

A tile to start the app will be available on the Start Screen.

Once the client starts, the Connect button should establish a WebSocket connection and the Send button will send a request to the web server. The response from the web server will delayed so the app will have time to be suspended. The resulting delayed WebSocket response will be received by the ControlChannelTrigger and a toast will be displayed.

Note  When the app is run under a debugger, it will not be suspended.