Handling exceptions in network apps (XAML)
[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 explains how to handle exceptions when using networking APIs in Windows Runtime apps written in C#, VB.NET, or managed C++.
What you need to know
Technologies
-
Enables network communications using sockets and WebSockets.
-
Provides a modern HTTP and REST client API for Windows Runtime apps.
Prerequisites
The following information applies to Windows Runtime apps that uses networking APIs to make remote connections. This topic applies to apps written in in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2.
For more information on handling exceptions in Windows Runtime apps written in JavaScript and HTML for Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2, see How to Handle exceptions in network apps.
Exceptions in network apps
When an exception occurs in an app, this indicates a significant problem or failure. Exceptions can occur for many reasons. Your code may have issues that may cause the exception. Other times, particularly using networking APIs, the exception can result from changes in network connectivity and other networking issues.
Reasons for exceptions when use networking APIs include the following:
- Parameter validation errors
- Name resolutions failures when looking up hostnames or URis
- Loss of network connectivity
- Network connection failures using sockets and HTTP client APIs
- Network server or remote endpoint errors
- Miscellaneous networking errors
Exceptions from network errors (loss of connectivity, connection failures, and HTTP server failures, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.
You must write code to handle exceptions when you call most asynchronous network methods. Sometimes when an exception occurs, a network method can be retried to try and resolve the problem. Other times, your app may need to plan to continue without network connectivity using previously cached data.
Windows Runtime apps generally throw a single exception. Your exception handler can retrieve more detailed information on the cause of the exception to better understand the failure and make appropriate decisions.
Each language projection supports a method to access this more detailed information. An exception projects as an HRESULT value in Windows Store apps. The Winerror.h include file contains a very large list of possible HRESULT values that includes network errors.
The networking APIs support different methods for retrieving this detailed information on the cause of an exception.
- A helper method that converts the HRESULT value from the exception to an enumeration value.
- The raw method depending on the language used to retrieve the HRESULT value.
Exceptions in Windows.Networking.Sockets
The constructor for the HostName class used with sockets can throw an exception if the string passed is not a valid hostname (contains characters that are not allowed in a host name). If an app gets input from the user for the HostName, the constructor should be in a try/catch block. If an exception is thrown, the app can notify the user and request a new hostname.
The Windows.Networking.Sockets namespace has convenient helper methods and enumerations for handling errors when using sockets and WebSockets. This can be useful for handling specific network exceptions differently in your app.
An error encountered on DatagramSocket, StreamSocket, or StreamSocketListener operation is returned as an HRESULT value. The SocketError.GetStatus method is used to convert a network error from a socket operation to a SocketErrorStatus enumeration value. Most of the SocketErrorStatus enumeration values correspond to an error returned by the native Windows sockets operation. An app can filter on specific SocketErrorStatus enumeration values to modify app behavior depending on the cause of the exception.
An error encountered on a MessageWebSocket or StreamWebSocket operation is returned as an HRESULT value. The WebSocketError.GetStatus method is used to convert a network error from a WebSocket operation to a WebErrorStatus enumeration value. Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP client operation. An app can filter on specific WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception.
For parameter validation errors, an app can also use the HRESULT from the exception to learn more detailed information on the error that caused the exception. Possible HRESULT values are listed in the Winerror.h header file. For most parameter validation errors, the HRESULT returned is E_INVALIDARG.
Exceptions in Windows.Networking.BackgroundTransfer
An exception is thrown when an invalid string for a the Uniform Resource Identifier (URI) is passed to the constructor for the Windows.Foundation.Uri object.
.NET: The Windows.Foundation.Uri type appears as System.Uri in C# and VB.
In C# and Visual Basic, this error can be avoided by using the System.Uri class in the .NET 4.5 and one of the System.Uri.TryCreate methods to test the string received from the app user before the URI is constructed.
In C++, there is no method to try and parse a string to a URI. If an app gets input from the user for the Windows.Foundation.Uri, the constructor should be in a try/catch block. If an exception is thrown, the app can notify the user and request a new hostname.
The Windows.Networking.backgroundTransfer namespace has convenient helper methods and uses enumerations in the Windows.Networking.Sockets namespace for handling errors. This can be useful for handling specific network exceptions differently in your app.
An error encountered on an asynchronous method in the Windows.Networking.backgroundTransfer namespace is returned as an HRESULT value. The BackgroundTransferError.GetStatus method is used to convert a network error from a background transfer operation to a WebErrorStatus enumeration value. Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP or FTP client operation. An app can filter on specific WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception.
For parameter validation errors, an app can also use the HRESULT from the exception to learn more detailed information on the error that caused the exception. Possible HRESULT values are listed in the Winerror.h header file. For most parameter validation errors, the HRESULT returned is E_INVALIDARG.
Exceptions in Windows.Web.Http
An exception is thrown when an invalid string for a the Uniform Resource Identifier (URI) is passed to the constructor for the Windows.Foundation.Uri object.
.NET: The Windows.Foundation.Uri type appears as System.Uri in C# and VB.
In C# and Visual Basic, this error can be avoided by using the System.Uri class in the .NET 4.5 and one of the System.Uri.TryCreate methods to test the string received from a user before the URI is constructed.
In C++, there is no method to try and parse a string to a URI. If an app gets input from the user for the Windows.Foundation.Uri, the constructor should be in a try/catch block. If an exception is thrown, the app can notify the user and request a new hostname.
The Windows.Web.Http lacks a convenience function. So an app using HttpClient and other classes in this namespace needs to use the HRESULT value.
In apps using the .NET Framework 4.5 in C#, VB.NET, the System.Exception represents an error during app execution when an exception occurs. The System.Exception.HResult property returns the HRESULT assigned to the specific exception. The System.Exception.Message property returns the message that describes the exception. Possible HRESULT values are listed in the Winerror.h header file. An app can filter on specific HRESULT values to modify app behavior depending on the cause of the exception.
In apps using managed C++, the Platform::Exception represents an error during app execution when an exception occurs. The Platform::Exception::HResult property returns the HRESULT assigned to the specific exception. The Platform::Exception::Message property returns the system-provided string that is associated with the HRESULT value. Possible HRESULT values are listed in the Winerror.h header file. An app can filter on specific HRESULT values to modify app behavior depending on the cause of the exception.
For most parameter validation errors, the HRESULT returned is E_INVALIDARG. For some illegal method calls, the HRESULT returned is E_ILLEGAL_METHOD_CALL.
Related topics
Other resources
Staying connected in the background
Transferring data in the background
Troubleshooting and debugging network connections
Reference