How to connect using System.Net.Http.HttpClient (Windows Store apps using C#/VB and XAML)

Article
10/13/2015

[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]

Use the HttpClient class in the System.Net.Http namespace to send a GET request to a web service and retrieve the response.

Note The System.Net.Http and System.Net.Http.Headers namespace might not be available in future versions of Windows for use by Windows Store apps. Starting with Windows 8.1 and Windows Server 2012 R2, use Windows.Web.Http.HttpClient in the Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces instead for Windows Runtime apps.

Classes in the System.Net.Http namespace provide a programming interface for modern HTTP apps. The System.Net.Http namespace and the related namespace provide HTTP client components that allow users to consume modern web services over HTTP.

The System.Net.Http.HttpClient class is used to send and receive basic requests over HTTP. It provides a base 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 System.Net.Http.HttpResponseMessage class represents an HTTP response message received from an HTTP request. HTTP messages are defined in RFC 2616 by the IETF.

The System.Net.Http.HttpContent class is a base class that represents an HTTP entity body and content headers. In this case, System.Net.Http.Http.Content is used to represent the HTTP response.

Prerequisites

The following examples in this topic are provided in C# using the .NET Framework 4.5. A basic understanding of HTTP requests as detailed in RFC 2616 is helpful in understanding this sample.

To make HTTP requests in a Windows Runtime app using C#/VB and XAML, see How to connect to an HTTP server using Windows.Web.Http.HttpClient. To make HTTP requests in a Windows Runtime app using C++ and XAML, see How to connect to an HTTP server using Windows.Web.Http.HttpClient and How to connect using XML HTTP Extended Request and IXMLHTTPRequest2.

To make HTTP requests in a Windows Runtime app using JavaScript and HTML, see Connecting to web services (HTML).

Create a new project

Open Microsoft Visual Studio 2013 and select New Project from the File menu.
In the list of templates, choose Visual C#.
Under the section, choose Store apps.
Under the section, select Windows apps and then select Blank Application.
Name the application HttpClientBasic and click OK.

Set capabilities to enable network access

You need to set network capabilities for your app to enable access to a private home or work network and to the Internet. For this app, you would need to enable network capabilities since the client is connecting to web services.

For an app using System.Net.Http.HttpClient to connect to a web service on a different computer, the app would need network capabilities set. If the app needs to be able to connect as a client to a web services on the Internet, then the Internet (Client) capability is needed. If the app needs to be able to connect as a client to web services on a home network or work network, then the Private Networks (Client & Server) capability is needed.

If the web service is running on the same computer as the app, this would require loopback access. Apps developed in Microsoft Visual Studio 2012 will automatically be registered as being exempt from the loopback restrictions. For more information, see How to enable loopback and debug network isolation.

For more information on network access, see How to configure network isolation capabilities.

The steps below are not needed for this sample if the web service is on the local computer. These steps are needed to set network capabilities for the app if it accesses a web service on the Internet or on a private or work network.

Use Visual Studio 2012 to open the package.appxmanifest file.
Select the Capabilities tab.
Select the Internet (Client) and Private Networks (Client & Server) capabilities.
Save and close the manifest file.

Add XAML UI

In this section, we define the app layout in XAML to specify the size and position of each object in the app. We complete the UI for the app by adding controls and content to display data.

This sample uses simple XAML UI elements that include the following:

A horizontal StackPanel that contains a TextBlock for a label, a TextBox for the input URI address, and a Button used to start the asynchronous request.
A horizontal StackPanel that contains a TextBlock for a label and a TextBox for the current status. This is where status and error messages will be displayed.

A Grid where the output received from the web service is displayed. In this sample, the result of the HTTP GET operation is displayed as plain text containing HTML markup.

Open the cs folder. Open the existing blankPage.html file and rename the file to MainPage.xaml. Add the following UI elements to this file.

<Page
    x:Class="HttpClientBasic.BlankPage"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:HttpClientBasic"
    xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">
        <StackPanel Orientation="Vertical">
            <StackPanel Orientation="Horizontal">
                <TextBlock Text="URI Address:" FontSize="16" Height="20"  Margin="15,0,0,0" />
                <TextBox x:Name="InputAddress" Text="https://www.contoso.com" FontSize="16" Height="20" Margin="15,0,0,0" />
                <Button Content="Start" Click="Start_Click" Margin="280,0,0,0" />
            </StackPanel>
            <StackPanel Orientation="Horizontal">
                <TextBlock Text="Status:" FontSize="16" Height="20" Margin="15,0,0,0" />
                <TextBox x:Name="StatusText" Text="Idle" FontSize="16" Height="Auto" TextWrapping="Wrap" Margin="15,0,0,0" />
            </StackPanel>
            <Grid 
                Grid.Column="1" Margin="15,0,0,0">
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="*" />
                </Grid.RowDefinitions>
                <TextBlock x:Name="OutputView" FontSize="16" Height="Auto" Margin="15,0,0,0" TextWrapping="Wrap" />
            </Grid>    
        </StackPanel>
     </Grid>
</Page>

Create the HttpClient, send the GET request, and retrieve the response

The code below first creates a System.Net.Http.HttpClient object.

First create the HttpClient object. We also set two properties on the HttpClient object.

The default size of the HttpClient.MaxResponseContentBufferSize property is the maximum size for an integer. To limit the amount of data the app accepts as a response from the web service , we set this property to a smaller value.

By default, no user-agent header is sent with the HTTP request to the web service by the HttpClient object. Some HTTP servers, including some Microsoft web servers, require that a user-agent header be included with the HTTP request sent from the client and return an error if no header is present. A user-agent header is added using the HttpClient.DefaultRequestHeaders property to avoid these errors.

Open the cs folder. Open the MainPage.cs file and add the following code to the file.
```
    private HttpClient httpClient;

    public BlankPage()
    {
        this.InitializeComponent();
        httpClient = new HttpClient();
        // Limit the max buffer size for the response so we don't get overwhelmed
        httpClient.MaxResponseContentBufferSize = 256000;
        httpClient.DefaultRequestHeaders.Add("user-agent", "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)");
    }
```
Send the GET request and retrieve the response.

Most of the work is done in the click handler for the Start Button. When this button is clicked, the text in the StatusText and OutputView UI elements is updated, then the input URI address is used to send the HTTP GET request and await the response. If an error or exception occurs, the result is displayed in the StatusText UI element. If no errors occur, the response from the web service is displayed in the OutputView UI element.

Using the await keyword in C# and Visual Basic, the code for sending the GET request and retrieving the response asynchronously is similar to the code we would use to complete this operation synchronously. You can use the await keyword only if the method is defined as async.

The HttpResponseMessage.EnsureSuccessStatusCode method throws an exception if the web server returned an HTTP error status code. Use a try/catch block for any exceptions and print out the exception message in the StatusText UI element if an error occurs. In the try block, print the status and response returned by the web service.

The HttpResponseMessage.Content property represents the content of the HTTP response. The HttpContent.ReadAsStringAsync method writes the HTTP content to a string as an asynchronous operation. We replace any <br> tags in the returned HTML text as newlines for display purposes.
```
        private async void Start_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                string responseBodyAsText;
                OutputView.Text = "";
                StatusText.Text = "Waiting for response ...";

                HttpResponseMessage response = await httpClient.GetAsync(InputAddress.Text);
                response.EnsureSuccessStatusCode();

                StatusText.Text = response.StatusCode + " " + response.ReasonPhrase + Environment.NewLine;
                responseBodyAsText = await response.Content.ReadAsStringAsync();
                responseBodyAsText = responseBodyAsText.Replace("<br>", Environment.NewLine); // Insert new lines
                OutputView.Text = responseBodyAsText;
            }
            catch (HttpRequestException hre)
            {
                StatusText.Text = hre.ToString();
            }
            catch (Exception ex)
            {
                // For debugging
                StatusText.Text = ex.ToString();
            }
        }
```
If an app using HttpClient and related classes in the System.Net.Http namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

The UriFormatException that is thrown when an invalid Uniform Resource Identifier (URI) is detected by members of the HttpClient class and related classes. This exception is not available for use in Windows Store apps. To catch this exception in that case, write a catch statement for FormatException instead.

Summary and next steps

In this topic we reviewed how to use the System.Net.Http.HttpClient class to send a GET request to a web service and retrieve the response using the System.Net.Http.HttpResponseMessage and System.Net.Http.HttpContent classes.

HttpClientBasic sample

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using Windows.Foundation;
using Windows.Foundation.Collections;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Controls.Primitives;
using Windows.UI.Xaml.Data;
using Windows.UI.Xaml.Input;
using Windows.UI.Xaml.Media;
using Windows.UI.Xaml.Navigation;

// The Blank Page item template is documented at https://go.microsoft.com/fwlink/p/?linkid=234238

namespace HttpClientBasic
{
    /// <summary>
    /// An empty page that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class BlankPage : Page
    {
        private HttpClient httpClient;

        public BlankPage()
        {
            this.InitializeComponent();
            httpClient = new HttpClient();
            // Limit the max buffer size for the response so we don't get overwhelmed
            httpClient.MaxResponseContentBufferSize = 256000;
            httpClient.DefaultRequestHeaders.Add("user-agent", "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)");
        }


        /// <summary>
        /// Invoked when this page is about to be displayed in a Frame.
        /// </summary>
        /// <param name="e">Event data that describes how this page was reached.  The Parameter
        /// property is typically used to configure the page.</param>
        protected override void OnNavigatedTo(NavigationEventArgs e)
        {
        }

        private async void Start_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                string responseBodyAsText;
                OutputView.Text = "";
                StatusText.Text = "Waiting for response ...";

                HttpResponseMessage response = await httpClient.GetAsync(InputAddress.Text);
                response.EnsureSuccessStatusCode();

                StatusText.Text = response.StatusCode + " " + response.ReasonPhrase + Environment.NewLine;
                responseBodyAsText = await response.Content.ReadAsStringAsync();
                responseBodyAsText = responseBodyAsText.Replace("<br>", Environment.NewLine); // Insert new lines
                OutputView.Text = responseBodyAsText;
            }
            catch (HttpRequestException hre)
            {
                StatusText.Text = hre.ToString();
            }
            catch (Exception ex)
            {
                // For debugging
                StatusText.Text = ex.ToString();
            }
        }
    }
}

The System.Net.Http.HttpClientHandler class can be used with the System.Net.Http.HttpClient class to set options on the HTTP request. For more information, see How to use System.Net.Htttp.HttpClient handlers.

Other resources

Connecting to web services

How to configure network capabilities

How to connect to an HTTP server using Windows.Web.Http.HttpClient

How to enable loopback and debug network isolation

How to secure System.Net.Http.HttpClient connections

How to use System.Net.Http.HttpClient handlers

Reference

System.Net.Http

System.Net.Http.Headers

Windows.Web.Http