How to re-establish a network trigger and transport connection (XAML)

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]

This topic shows how to re-establish a network trigger and transport connection to maintain background network connectivity in a Windows Store app when it becomes necessary. This topic shows you how to re-establish a network trigger and transport connection when using ControlChannelTrigger.

What you need to know

Technologies

Windows.Networking.Sockets

Enables network communications using sockets and WebSockets and supports the ControlChannelTrigger object.
IXMLHTTPRequest2

Enables access to Web resources using an extension to XMLHttpRequest object.
System.Net.Http

Enables connecting to web services with a modern web client.

Prerequisites

The following information applies to any connected or network-aware Windows Store app that depends on network connections using TCP to always be connected. This topic applies to apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8 and Windows Server 2012.

This topic does not apply to apps written in JavaScript or a foreground app in JavaScript with an in-process C# or C++ binary. Background network connectivity using a network trigger with ControlChannelTrigger is not supported by a JavaScript app. For information on background tasks that apply to JavaScript apps, see Supporting your app with background tasks. For information on background network connectivity supported by a JavaScript app, see Staying connected in the background (HTML).

Instructions

Step 1: Re-establish a network trigger and transport connection

The app will be always reachable only if the control channel is open between the client and remote end point. This section discusses a few scenarios where an app needs to re-establish a ControlChannelTrigger.

User sign in through a system event trigger

When a user logs off, the app's control channel is broken. When the user logs back on, the user shouldn’t have to restart the app in order to receive email or VoIP calls. To make this seamless and have the ability to register a network trigger on user logon, there is a system event trigger type for SessionConnected. This trigger type can also occur as a result of a computer being unlocked after fast user switching. An app may choose to distinguish the case of a user logon (check if the app state is initiated) versus other possible cases. This event can be used as a proxy for the user logon event. This event will be raised only for an app that has been added to the lock screen.

The following sample shows how to register for the SessionConnected system trigger type.
```
//
// Create a new SessionStart trigger. 
//
BackgroundTaskBuilder UserLogin = new BackgroundTaskBuilder();

SystemTrigger myTrigger = new SystemTrigger(SystemTriggerType.SessionConnected, false);

UserLogin.SetTrigger(myTrigger);
UserLogin.Name = "UserLoginSystemTrigger";
UserLogin.TaskEntryPoint = UserLoginEntryPointClassName;
UserLogin.Register();
```

Network change event through system event trigger

When a user roams between networks (a user travels from home to work, for example), the network will disconnect at one location and reconnect at another. Upon this transition, the user expects to remain connected to important network services (able to receive VoIP calls, for example). To enable such scenarios, your app must register for the InternetAvailable or NetworkStateChange system event triggers. These triggers will occur when the availability to the Internet changes or the network state changes including when connectivity has been restored, so your app can re-register for the network trigger or reconnect the transport object and use it with the existing network trigger. To register for these triggers, your app must also have the triggers set in the app manifest.

The following sample shows how to register for the NetworkStateChange system trigger type.
```
BackgroundTaskBuilder NwkChange = new BackgroundTaskBuilder();

//
// Create a new Network State Change trigger. 
//
SystemTrigger myTrigger = new SystemTrigger(SystemTriggerType.NetworkStateChange, false);

NwkChange.SetTrigger(myTrigger);
NwkChange.Name = "NwkChangeSystemTrigger";
NwkChange.TaskEntryPoint = NetworkStateChangeTaskClassName;
NwkChange.Register();
```

Fast user switching

Windows supports fast user switching (FUS), where multiple users can share a device. In Windows 8, the network trigger is supported only for the last active user session that has been attached to the console of the device. When another user logs on to Windows using the console, the connection using the network trigger for the previously logged on user is aborted and the associated hardware or software slot is released. The ControlChannelTrigger object remains re-usable.

When the new user logs on or a user unlocks a previously inactive session, there is a ControlChannelReset that an app can register for to indicate that a ControlChannelTrigger was reset. This indicates that the previous user is cleaned up and Windows is ready for the current active user. This trigger can be used to register a ControlChannelTrigger and establish the transport connection to the remote endpoint server.

The following sample shows how to register for the ControlChannelReset system trigger type.
```
BackgroundTaskBuilder NtfChannelReset = new BackgroundTaskBuilder();

//
// Create a new FUS trigger. 
//
SystemTrigger myTrigger = new SystemTrigger(SystemTriggerType.ControlChannelReset, false);
NtfChannelReset.SetTrigger(myTrigger);
NtfChannelReset.NwkChange.Name = "FUSSystemTrigger";
NtfChannelReset.TaskEntryPoint = FUSTriggerTaskClassName;
NtfChannelReset.Register();
```
If an application registers for ControlChannelReset, this covers the scenarios related to fast user switching and connected standby. For the user login scenario, the SessionConnected event should also be used.

When switching users through fast user switching, the ControlChannelReset system trigger type occurs indicating to the app that the ControlChannelTrigger object is ready to be used for the new user.

When the ControlChannelTrigger is using a software slot and the system enters connected standby, the connection using the network trigger is aborted and the associated software slot is released. The ControlChannelTrigger object is re-usable. When the system exits from connected standby, the app using software slots has to re-establish the ControlChannelTrigger object or re-establish the network connection and use it with the existing ControlChannelTrigger object. The ControlChannelReset system trigger type also occurs when system exits connected standby.

A ControlChannelTrigger object with a hardware slot will be preserved through connected standby.

Triggering control channel registration when added to lock screen

An app needs a way to be notified when the app is manually added to the lock screen by the user so the app to register ControlChannelTrigger objects. For example, if a user dismisses the lock screen permission dialog when app is first run and then decides to manually allow the app in PC settings, this should trigger an event so that the app can complete ControlChannelTrigger registration. In order to ensure that ControlChannelTrigger object registration succeeds, your app must be on the lock screen. So, your app should register for the LockScreenApplicationAdded system trigger type.

The following sample shows how to register for the LockScreenApplicationAdded system trigger type.
```
BackgroundTaskBuilder LockScreenCCT = new BackgroundTaskBuilder();

//
// Create a new lock screen trigger. 
//
SystemTrigger myTrigger = new 
   SystemTrigger(SystemTriggerType.LockScreenApplicationAdded, false);

LockScreenCCT.SetTrigger(myTrigger);
LockScreenCCT.Name = "LockScreenAddedTrigger";
LockScreenCCT.TaskEntryPoint = LockScreenAddedTaskClassName;
LockScreenCCT.Register();
```

Retry logic using network status change

A connected Windows Store app needs a trigger through which they can re-establish connectivity to the remote endpoint on a network change.

A network change includes any of the following conditions.
- Network interface change - There is an interface change from one network to another. For example, roaming from wireless LAN at home to a wireless LAN at work, or moving from a wireless LAN to mobile broad band.
- Network path change - End to end connectivity could be broken due to an intermediate network outage. For example, if a user is connected through an ISP and the ISP experiences an outage, then a network path change can occur.
- Network interface policy changes - Policy changes can cause changes to the routes over which an app can establish its connectivity.
When there is a change in any one of the above, a NetworkStateChange system trigger type occurs.

Since the NetworkStateChange triggers when any of the above conditions occur, certain scenarios cause more than one NetworkStateChange trigger to occur. When this happens, an app could choose to optimize by checking for the internetAvailable condition. This would provide an indication to the app to do some activity.

Step 2: Previous steps

For more information on how to create a lock screen app to receive background network notifications that use network triggers, see Quickstart: Create a lock screen app that uses background network triggers.

For more information on how to use network triggers to deliver notifications to a lock screen app, see How to use network triggers to deliver notifications to a lock screen app.

For more information on how to write a background task to receive background network notifications that use network triggers, see How to write a background task for a network trigger.