Guidelines for connection usage data
Consider the following recommendations when using Windows Runtime Network Information APIs in your connected app.
Modifying app behavior according to network cost type
Although Windows 8 automatically provides connectivity options when a device detects new networks, there is no guarantee of a seamless transition from existing connections to new networks for every operation. A Windows Store app that connects to destinations on the Web should use Network Information APIs to obtain cost information and status change events for the network on which they are sending and receiving data.
Use the NetworkCostType value indicated for each connection to modify its behavior appropriately:
Network Cost Type | Recommended App Behavior |
---|---|
Unrestricted |
|
Variable/Approaching Data Cap |
|
Unknown |
|
Maintaining a reliable connection to the Web
One of the most fundamental ways your app can demonstrate agility in the network space is by maintaining a consistent level of quality when interfacing with the Web. This can be done by leveraging the information provided by the connection profile and subsequent network status change notifications and by identifying available networks that meet current requirements.
All Windows Store apps should do the following to support Web connectivity:
- Call GetInternetConnectionProfile to check the cost of connecting to the Internet.
- Register for network status change notifications for the connection.
- Initialize the network operation on the connection.
- When a network status changed notification is received, the cost/connectivity options available may have changed. The app should:
- Check the cost of connecting to the Internet. If the cost characteristic has changed from unrestricted to metered or from metered to unrestricted, retry the network operation. Windows will automatically use the lowest cost network available.
- If the cost characteristic of connecting to the Internet has not changed, but a cost related notification is received (for example, >80% cap consumed, variable cost, roaming, etc.), adapt behavior as suggested in the NetworkCostType table above.
- If an error indicates that the connection went away, the app should:
- Check the cost of connecting to the Internet via another available network. Follow the guidelines provided in the NetworkCostType table above.
- Retry the operation; if this fails, then wait for a NetworkStatusChange notification.
Debugging and troubleshooting your connected app
Network glitches can cause applications to hang, crash, or show non-actionable dialog boxes and confusing error messages to the users. Debugging these errors can be difficult because errors can occur anywhere within the networking stack.
All Windows Store apps that use the network either directly (using sockets) or indirectly (using an API that eventually uses the network) are impacted. The ideal situation is for the operating system to handle error conditions automatically on behalf of the developer and when that does not work applications should be prepared to deal with errors.
All connected Windows Store 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 the network you were communicating on went away because another one may be available. Many errors can simply go away when retrying the operation. 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. In other words, if a networking operation takes a long time to complete or there is an error, your application should not hang. Do not emulate synchronous behavior on top of the asynchronous nature of the Windows Runtime.
- 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, enable ETW tracing.
Security Considerations
The following articles provide guidance for writing secure C++ code.
Related topics
Developing connected applications (Whitepaper)
For developers (HTML)
Connection state and cost management
For developers (XAML)