WebRequestExtensions.SetNetworkPreference Method

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Sets the preference for a web request to use either cellular or non-cellular technology.

Namespace:  Microsoft.Phone.Net.NetworkInformation
Assembly:  Microsoft.Phone (in Microsoft.Phone.dll)

Syntax

<ExtensionAttribute> _
Public Shared Sub SetNetworkPreference ( _
    request As WebRequest, _
    preference As NetworkSelectionCharacteristics _
)

public static void SetNetworkPreference(
    this WebRequest request,
    NetworkSelectionCharacteristics preference
)

Parameters

• request
  Type: System.Net..::.WebRequest
  The web request for which to set the preference.

• preference
  Type: Microsoft.Phone.Net.NetworkInformation..::.NetworkSelectionCharacteristics
  One of the enumeration values that specify the preferred type of technology.

Usage Note

In Visual Basic and C#, you can call this method as an instance method on any object of type WebRequest. When you use instance method syntax to call this method, omit the first parameter.

Exceptions

Remarks

This method must be called before calling BeginGetResponse. Otherwise, an InvalidOperationException will be thrown.

For more information about extension methods, see Extension Methods (C# Programming Guide) or How to: Call an Extension Method (Visual Basic).

Examples

The following code example shows how to use the SetNetworkPreference extension method. In this example, the preferred network interface is Cellular. If a cellular network interface is not available, another network interface is used. GetCurrentNetworkInterface is called in the request callback to determine what network interface was used.

private void StartDownload()
{
   HttpWebRequest request;

   // A NetworkException with the error NetworkError.WebRequestAlreadyFinished will
   // be thrown if GetCurrentNetworkInterface is called after the request is complete.
   // The uri string used here is for illustration purposes only. It may complete before
   // you call GetCurrentNetworkInterface. Replace this with a longer-running request if needed.
   request = (HttpWebRequest)WebRequest.Create("https://www.contoso.com/example.aspx");
   request.AllowReadStreamBuffering = false;

   // Our preference, for this example, is a cellular network interface. 
   // Call SetNetworkPreference on an HttpWebRequest before calling BeginGetResponse or
   // an InvalidOperationException will be thrown.
   request.SetNetworkPreference(NetworkSelectionCharacteristics.Cellular);
   IAsyncResult result = (IAsyncResult)request.BeginGetResponse(new AsyncCallback(response_Callback), request);                     
}       

private void response_Callback(IAsyncResult asyncResult)
{                      
   HttpWebRequest request = (HttpWebRequest)asyncResult.AsyncState;

   // Check to see what network interface is being used. 
   // The call to GetCurrentNetworkInterface must be invoked on the UI thread.
   Dispatcher.BeginInvoke(() =>
   {
      try
      {
         NetworkInterfaceInfo ni = request.GetCurrentNetworkInterface();

      // If a cellular interface was available, we should see that here, since that was our
      // preference. Otherwise, we will get a different network interface type, such as Ethernet
      System.Diagnostics.Debug.WriteLine(ni.InterfaceType.ToString());    
      }
      catch (NetworkException networkException)
      {
         // If the HttpWebRequest was not long running, then this exception will be thrown for
         // the GetCurrentNetworkInterface above.
         if (networkException.NetworkErrorCode == NetworkError.WebRequestAlreadyFinished)
         {
            System.Diagnostics.Debug.WriteLine("Cannot call GetCurrentNetworkInterface if the web request is already complete");
         }
      }
   });       
}               
 

Version Information

Windows Phone OS

Supported in: 8.1, 8.0, 7.1

Platforms

Windows Phone

See Also

Reference

WebRequestExtensions Class

Microsoft.Phone.Net.NetworkInformation Namespace