This sample shows you how to upload and download various types of content with an HTTP server using the HttpClient and related classes in Windows.Web.Http namespace in your Windows Runtime app.
Note This sample was created using one of the universal app templates available in Visual Studio. It shows how its solution is structured so it can run on both Windows 8.1 and Windows Phone 8.1. For more info about how to build apps that target Windows and Windows Phone with Visual Studio, see Build apps that target Windows and Windows Phone 8.1 by using Visual Studio.
This sample shows the use of asynchronous GET and POST requests using HttpClient. The sample also shows the use of caching and filters. Example filters are provided to handle retries and metered network connections. Versions of this sample are provided in JavaScript, C#, VB, and C++.
The HttpClient class is used to send and receive basic requests over HTTP. It is the main class for sending HTTP requests and receiving HTTP responses from a resource identified by a URI. This class can be used to send a GET, PUT, POST, DELETE, and other requests to a web service. Each of these requests is sent as an asynchronous operation. The HttpClient class can be used in scenarios that use text as well as scenarios that use arbitrary streams of data.
The Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces in Windows 8.1, Windows Server 2012 R2, and later provide a programming interface for Windows Runtime apps that target HTTP services. The new HTTP API provides consistent support in JavaScript, C#, VB.NET, and C++ for developers. This new API replaces the use of three different APIs with differing features that previously were needed for each language projection in Windows 8.
Classes in the Windows.Web.Http.Headers namespace represent HTTP headers defined in RFC 2616 by the IETF. HTTP headers are associated with HttpRequestMessage and HttpResponseMessage objects as properties that are retrieved or set.
Classes in the Windows.Web.Http namespace can use filters based on the classes in the Windows.Web.Http.Filters namespace. Filters provide a handler to help with common HTTP web service issues. Filters can be chained together in a sequence to address more complex web service issues. Two filters are included in this sample to handle metered network connections and retry. The sample also shows how to use the HttpCacheControl class in the Windows.Web.Http.Filters namespace to control read or write cache behavior.
Note The Windows version of this sample by default requires network access using the loopback interface.
For a sample that shows how to use HttpClient so that the app is always connected and always reachable using background network notifications in a Windows Store app, download the ControlChannelTrigger HttpClient sample .
Network capabilities
This sample requires that network capabilities be set in the Package.appxmanifest file to allow the app to access the network at runtime. These capabilities can be set in the app manifest using Microsoft Visual Studio.
To build the Windows version of the sample, set the following network capabilities:
-
Internet (Client): The sample can use the Internet for GET and POST operations (outbound-initiated access). This allows the app to download various types of content from an HTTP server and upload content to an HTTP server located on the Internet. This is represented by the Capability name = "internetClient" tag in the app manifest.
Private Networks (Client & Server): The sample has inbound and outbound network access on a home or work network (a local intranet). This allows the app to download various types of content from an HTTP server and upload content to an HTTP server located on a local intranet. The Private Networks (Client & Server) capability is represented by the Capability name = "privateNetworkClientServer" tag in the app manifest.
To build the Windows Phone version of the sample, set the following network capabilities:
-
Internet (Client & Server): This sample has complete access to the network for both client operations (outbound-initiated access) and server operations (inbound-initiated access). This allows the app to download various types of content from an HTTP server and upload content to an HTTP server located on the Internet or on a local intranet. This is represented by the Capability name = "internetClientServer" tag in the app manifest.
Note On Windows Phone, there is only one network capability which enables all network access for the app.
For more information on network capabilities, see How to set network capabilities.
Note Network communications using an IP loopback address cannot normally be used for interprocess communication between a Windows Runtime app and a different process (a different Windows Runtime app or a desktop app) because this is restricted by network isolation. Network communication using a loopback address to a different process is allowed when the app is run under the debugger. For more information, see How to enable loopback and troubleshoot network isolation.
To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.
To obtain an evaluation copy of Microsoft Visual Studio 2013 Update 2, go to Microsoft Visual Studio 2013.
Note For Windows 8 app samples, download the Windows 8 app samples pack. The samples in the Windows 8 app samples pack will build and run only on Microsoft Visual Studio 2012.
Related topics
- Other - C#/VB/C++ and XAML
- Adding support for networking (XAML)
- Connecting to network services (XAML)
- >Connecting with WebSockets (XAML)
- How to connect to an HTTP server using Windows.Web.Http Windows.Web.Http.HttpClient (XAML)
- How to set network capabilities (XAML)
- Staying connected in the background (XAML)
- Troubleshooting and debugging network connections
- Other - JavaScript and HTML
- Adding support for networking (HTML)
- Connecting to network services (HTML)
- Connecting with WebSockets (HTML)
- How to connect to an HTTP server using Windows.Web.Http (HTML)
- How to set background connectivity options (HTML)
- How to set network capabilities (HTML)
- Troubleshooting and debugging network connections
- Other resources
- Adding support for networking
- Connecting to a WebSocket service
- How to configure network isolation capabilities
- How to secure HttpClient connections
- Quickstart: Connecting using HttpClient
- Reference
- HttpClient
- Windows.Web.Http
- Windows.Web.Http.Headers
- Windows.Web.Http.Filters
- Samples
- ControlChannelTrigger HttpClient sample
- Windows 8 app samples
Operating system requirements
| Client | |
|---|---|
| Server | |
| Phone |
Build the sample
- Start Visual Studio 2013 Update 2 and select File > Open > Project/Solution.
- Go to the directory to which you unzipped the sample. Go to the directory named for the sample, and double-click the Visual Studio 2013 Update 2 Solution (.sln) file.
- Follow the steps for the version of the sample you want:
-
To build the Windows version of the sample:
- Select HttpClient.Windows in Solution Explorer.
- Press Ctrl+Shift+B, or use Build > Build Solution, or use Build > Build HttpClient.Windows.
-
To build the Windows Phone version of the sample:
- Select HttpClient.WindowsPhone in Solution Explorer.
- Press Ctrl+Shift+B or use Build > Build Solution or use Build > Build HttpClient.WindowsPhone.
-
Run the sample
The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.
Deploying the sample
-
To deploy the built Windows version of the sample:
- Select HttpClient.Windows in Solution Explorer.
- Use Build > Deploy Solution or Build > Deploy HttpClient.Windows.
-
To deploy the built Windows Phone version of the sample:
- Select HttpClient.WindowsPhone in Solution Explorer.
- Use Build > Deploy Solution or Build > Deploy HttpClient.WindowsPhone.
Deploying and running the Windows version of the sample
This sample requires that a web server is available for the app to access for uploading and downloading files. The web server must be started before the app is run. The web server must also have an HttpClientSample path available for uploads and downloads. The sample includes a PowerShell script that will install IIS on the local computer, create the HttpClientSample folder on the server, copy files to this folder, and enable IIS.
The easiest way to run the sample is to use the provided web server scripts. Browse to the Server folder in your sample folder to setup and start the web server. There are two options possible.
- Start PowerShell elevated (Run as administrator) and run the following command:
.\SetupServer.ps1
Note that you may also need to change script execution policy.
- Start an elevated Command Prompt (Run as administrator) and run following command:
PowerShell.exe -ExecutionPolicy Unrestricted -File SetupServer.ps1
When the web server is not needed anymore, please browse to the Server folder in you sample folder and run one of the following:
- Start PowerShell elevated (Run as administrator) and run the following command:
.\RemoveServer.ps1
Note that you may also need to change script execution policy.
- Start an elevated Command Prompt (Run as administrator) and run following command:
PowerShell.exe -ExecutionPolicy Unrestricted -File RemoveServer.ps1
The sample can run using other web servers, not only the one provided with the sample. However for scenarios in the sample, the web server may need to be configured to interpret the query string and cookies similar to IIS so it can send the expected responses.
If IIS is used on a different computer, then the previous scripts can be used with minor changes.
- Copy the Server folder to the device where IIS will be run.
- Run the above scripts to install IIS, create the HttpClientSample folder on the server, copy files to this folder, and enable IIS.
The sample must also be updated when run against a non-localhost web server. To configure the sample for use with IIS on a different device:
- The hostname of the server to connect to needs to be updated. This can be handled in two ways. The AddressField element in the HTML or XAML files can be edited so that "localhost" is replaced by the hostname or IP address of the web server. Alternately when the app is run, enter the hostname or IP address of the web server instead of the "localhost" value in the Address textbox.
Note IIS is not available on ARM builds nor on Windows Phone. Instead, set up the web server on a separate 64-bit or 32-bit computer and follow the steps for using the sample against non-localhost web server.
Note When used with the supplied scripts, this Windows Runtime app sample communicates with another process (IIS server which is a desktop app) on the same machine over loopback for demonstration purposes only. A Windows Runtime app that communicates over loopback to another process that represents a Windows Runtime app or a desktop app is not allowed and such apps will not pass Store validation. For more information, see How to enable loopback and troubleshoot network isolation.
However if a server different than IIS is used, then this requires some special configuration of the server to create the HttpClientSample folder.
- Copy the Server\webSite directory to the HttpClientSample folder on the web server and configure the server to allow GET and POST requests.
To configure the sample for use with a web server different than IIS not using localhost:
- The target URI field should be updated. This can be handled in two ways. The AddressField element in the HTML or XAML files can be edited so that the URI is replaced by a URI for the non-IIS server. Alternately when the app is run, enter the URI to access on the web server instead of the default value in the Address textbox.
-
To deploy and run the Windows version of the sample:
- Right-click HttpClient.Windows in Solution Explorer and select Set as StartUp Project.
- To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
Deploying and running the Windows Phone version of the sample
IIS is not available on Windows Phone. For the app to access a web server, there are two options:
- The easiest way to run the sample is to use the provided web server scripts on a separate 64-bit or 32-bit device that can run IIS. Follow the instructions for deploying and running the Windows version of the sample using IIS on a different device.
- Use a web server different than IIS on a separate device. Follow the instructions for deploying and running the Windows version of the sample using a non-IIS web server.
-
To deploy and run the Windows Phone version of the sample:
- Right-click HttpClient.WindowsPhone in Solution Explorer and select Set as StartUp Project.
- To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.