| page_type | languages | products | urlFragment | extendedZipContent | description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sample |
|
|
HttpClient |
|
Shows how to upload and download various types of content with an HTTP server. |
Shows how to upload and download various types of content with an HTTP server using the HttpClient and related classes in Windows.Web.Http namespace.
Note: This sample is part of a large collection of UWP feature samples. You can download this sample as a standalone ZIP file from docs.microsoft.com, or you can download the entire collection as a single ZIP file, but be sure to unzip everything to access shared dependencies. For more info on working with the ZIP file, the samples collection, and GitHub, see Get the UWP samples from GitHub. For more samples, see the Samples portal on the Windows Dev Center.
This sample shows the use of asynchronous GET and POST requests using HttpClient. 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. Filters (see Windows.Web.Http.Filters namespace) provide a way to modify the request/response flow of HTTP and handle common HTTP web service issues. Filters can be chained together in a sequence to address more complex web service issues.
The sample covers the following scenarios:
Scenario 1: Use HTTP GET command to download HTML text from a server, using various caching options
Scenario 2: Use HTTP GET command to download a stream from a server
Scenario 3: Use HTTP GET command to download a list of items in XML format from a server
Scenario 4: Use HTTP POST command to upload text to a server
Scenario 5: Use HTTP POST command to upload a stream to a server
Scenario 6: Use HTTP POST command to upload a MIME form using a HttpMultipartFormDataContent class
Scenario 7: Use HTTP POST command to upload a stream - use progress indicator and request/response encoding settings
Scenario 8: Use HTTP POST command to upload custom content
Scenario 9-12: Query for cookies, set new cookies, delete existing cookies, and disable cookies
Scenario 13: Use a filter to retry HTTP requests if required
Scenario 14: Use a filter to adapt download behavior based on whether the device is on a metered network connection or not
Scenario 15: Validate the server certificate
Note 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 Universal Windows Platform (UWP) app, download the ControlChannelTrigger HttpClient sample .
This sample uses the Try versions of the HttpClient methods which do not raise exceptions. For a version that uses the exception-based methods, see the v7.0.6 sample.
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 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.
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.
For more information on network capabilities, see How to set network capabilities.
Adding support for networking (XAML)
Connecting to network services (XAML)
Connecting with WebSockets (XAML)
HttpClient
Networking basics
Troubleshooting and debugging network connections
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
Adding support for networking
Connecting to a WebSocket service
How to configure network isolation capabilities
How to secure HttpClient connections
Quickstart: Connecting using HttpClient
HttpClient
Windows.Web.Http
Windows.Web.Http.Headers
Windows.Web.Http.Filters
Client: Windows 10 version 1604 preview
Server: Windows Server 2016 Technical Preview
Phone: Windows 10 version 1604 preview
- If you download the samples ZIP, be sure to unzip the entire archive, not just the folder with the sample you want to build.
- Start Microsoft Visual Studio and select File > Open > Project/Solution.
- Starting in the folder where you unzipped the samples, go to the Samples subfolder, then the subfolder for this specific sample, then the subfolder for your preferred language (C++, C#, or JavaScript). Double-click the Visual Studio Solution (.sln) file.
- Press Ctrl+Shift+B, or select Build > Build Solution.
The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.
- Select Build > Deploy Solution.
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 or websites, 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 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 sample communicates with another process (IIS server which is a desktop app) on the same machine over loopback for demonstration purposes only. A UWP app that communicates over loopback to another process that represents a UWP app or a desktop app is not allowed and such apps will not pass Microsoft 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.
Once the server is ready, you can deploy and run the sample:
- 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.