Troubleshooting and debugging network connections (Windows Runtime apps)
Network issues can cause applications to stop responding, crash, or show non-actionable dialog boxes and confusing error messages to the users. Troubleshooting and debugging these errors can be difficult because errors can occur anywhere within the networking stack.
Who is impacted
All Windows Runtime apps that use the network either directly (using sockets, for example) or indirectly (using an API that eventually uses the network) are potentially impacted by network issues. The ideal situation is for the operating system to automatically handle network error conditions on behalf of the application and when that does not work, applications should be prepared to deal with errors.
Selecting the right network capability
For a Windows Runtime app to access the network, certain networking isolation capabilities must be enabled in the manifest for the app. These capabilities are normally configured using Microsoft Visual Studio 2013 when the app is developed. These capabilities are enforced by Windows. If the appropriate network capability has not been set, network access may be blocked.
So the first step when troubleshooting network issues is to verify that the appropriate network capabilities have been configured for the app.
| Network Capability | Description |
|---|---|
privateNetworkClientServer |
|
internetClient |
|
internetClientServer |
|
proximity |
Allows two machines that are in close physical proximity (up to one foot) to be able to interact with one another using the Windows.Networking.Proximity namespace features. |
Once you have determined the required network access for your app, make sure that the appropriate network capability settings have been configured. Failure to do so will block network access.
For information on how to enable loopback for network access and troubleshoot network isolation issues, see How to enable loopback and debug network isolation.
Reacting to network status changes
When Windows 8.1, Windows Phone 8.1, or Windows Server 2012 R2 detects new networks, it will automatically provide new connectivity options. For instance, if a user is using his 3G network to stream data and later comes into range of a Wi-Fi network, the new connectivity option will be available for the application if it makes sense to do so.
In any mobile device scenario, networks can come and go. A 3G network could go out of range within a user’s home or workplace while Wi-Fi is still available; similarly, Wi-Fi may go out of range when a user leaves home or work. Additionally, there may be times when no network is available. Given the proliferation of Wi-Fi and mobile broadband networks, such network changes (networks coming, going, or not being available) will be common. Connections do not automatically switch over to a new network seamlessly; the application needs to get involved. Note that the default policy in Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2 is to pick the unrestricted network over the metered network and the faster network over the slower network.
Network access may be affected any time network changes occur. An app can register for network status change notifications (onNetworkStatusChanged) so it is notified when these network changes occur. If the connection the app was using is no longer available (indicated by an error), the app may need to do one of the following:
- Retry the operation. If this fails, then wait for another NetworkStatusChanged notification.
- Check the network cost and try to connect to a different network.
Basic Troubleshooting Guidance
Windows Runtime apps need to do the following:
When a networking error happens, retry the operation if appropriate. For instance, do not retry the operation if authentication fails, but retry the operation if a wireless network you were communicating with disappeared because another wireless network may be available. Many errors simply disappear when the operation is retried. On retrying, follow the guidelines specified earlier in Reacting to network status changes.
Ensure that you use asynchronous APIs so that there is no blocking call on the UI thread. If a networking operation takes a long time to complete or there is an error, your application should not stop responding. Do not emulate synchronous behavior on top of the asynchronous nature of the Windows Runtime.
Have a model for handling errors planned in advance. Think through how to expose error information to the user as you design your application. For example, Outlook uses a discreet network indicator; Communicator has a "replace the whole UI" scheme; Internet Explorer includes a task-oriented dialog box for downloads that displays network errors. Catch errors and exceptions for cases where an exception is thrown. Understand each of the error strings, and appropriately inform the user.
Test your application in various networking environments with activities like disconnecting or reconnecting to your network, suspending or resuming, or switching from one network to another.
When you are testing your application and find errors that are not immediately obvious, you can enable ETW tracing to collect more details on the issue.