This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Download Microsoft Edge More info about Internet Explorer and Microsoft Edge

The HttpClient Stack and SSL/TLS Implementation selectors determine the HttpClient and SSL/TLS implementation that will be used by your Xamarin.Android apps.

Projects must reference the System.Net.Http assembly.

Warning

April, 2018 – Due to increased security requirements, including PCI compliance, major cloud providers and web servers are expected to stop supporting TLS versions older than 1.2. Xamarin projects created in previous versions of Visual Studio default to use older versions of TLS.

In order to ensure your apps continue to work with these servers and services, you should update your Xamarin projects with the Android HttpClient and Native TLS 1.2 settings shown below, then re-build and re-deploy your apps to your users.

The Xamarin.Android HttpClient configuration is in Project Options > Android Options , then click the Advanced Options button.

These are the recommended settings for TLS 1.2 support:

The Xamarin.Android HttpClient configuration is in Project Options > Build > Android Build settings and click on the General tab.

These are the recommended settings for TLS 1.2 support:

Alternative configuration options

AndroidClientHandler

AndroidClientHandler is the new handler that delegates to native Java/OS code instead of implementing everything in managed code. This is the recommended option.

Use native API for better performance and smaller executable size.

Support for the latest standards, eg. TLS 1.2.

Requires Android 4.1 or later.

Some HttpClient features/options are not available.

Managed (HttpClientHandler)

Managed handler is the fully managed HttpClient handler that has been shipped with previous Xamarin.Android versions.

It is the most compatible (features) with MS .NET and older Xamarin versions.

It is not fully integrated with the OS (eg. limited to TLS 1.0).

It is usually much slower (eg. encryption) than native API.

It requires more managed code, creating larger applications.

Choosing a Handler

The choice between AndroidClientHandler and HttpClientHandler depends upon the needs of your application. AndroidClientHandler is recommended for the most up-to-date security support, eg.

You require TLS 1.2+ support.

Your app is targeting Android 4.1 (API 16) or later.

You need TLS 1.2+ support for HttpClient .

You don't need TLS 1.2+ support for WebClient .

HttpClientHandler is a good choice if you need TLS 1.2+ support but must support versions of Android earlier than Android 4.1. It is also a good choice if you need TLS 1.2+ support for WebClient .

Beginning with Xamarin.Android 8.3, HttpClientHandler defaults to Boring SSL ( btls ) as the underlying TLS provider. The Boring SSL TLS provider offers the following advantages:

It supports TLS 1.2+.

It supports all Android versions.

It provides TLS 1.2+ support for both HttpClient and WebClient .

The disadvantage of using Boring SSL as the underling TLS provider is that it can increase the size of the resulting APK (it adds about 1MB of additional APK size per supported ABI).

Beginning with Xamarin.Android 8.3, the default TLS provider is Boring SSL ( btls ). If you do not want to use Boring SSL, you can revert to the historical managed SSL implementation by setting the $(AndroidTlsProvider) property to legacy (for more information about setting build properties, see Build Process ).

Programatically Using AndroidClientHandler

The Xamarin.Android.Net.AndroidClientHandler is an HttpMessageHandler implementation specifically for Xamarin.Android. Instances of this class will use the native java.net.URLConnection implementation for all HTTP connections. This will theoretically provide an increase in HTTP performance and smaller APK sizes.

This code snippet is an example of how to explicitly for a single instance of the HttpClient class:

// Android 4.1 or higher, Xamarin.Android 6.1 or higher
HttpClient client = new HttpClient(new Xamarin.Android.Net.AndroidClientHandler ());
The underlying Android device must support TLS 1.2 (ie. Android 4.1 and later). Please note that the official support for TLS 1.2 is in Android 5.0+. However some devices support TLS 1.2 in Android 4.1+.
SSL/TLS implementation build option
This project option controls what underlying TLS library will be used
by all web request, both HttpClient and WebRequest. By default, TLS
1.2 is selected:
Visual Studio
Visual Studio for Mac
var client = new HttpClient();
If the HttpClient implementation was set to Managed and the TLS
implementation was set to Native TLS 1.2+, then the client object
would automatically use the managed HttpClientHandler and TLS 1.2
(provided by the BoringSSL library) for its HTTP requests.
However, if the HttpClient implementation is set to
AndroidHttpClient, then all HttpClient objects will use the
underlying Java class java.net.URLConnection and will be unaffected
by the TLS/SSL implementation value. WebRequest objects would use
the BoringSSL library.
Other ways to control SSL/TLS configuration
There are three ways that a Xamarin.Android application can control the TLS settings:
Select the HttpClient implementation and default TLS library in the Project Options.
Programatically using Xamarin.Android.Net.AndroidClientHandler.
Declare environment variables (optional).
Of the three choices, the recommended approach is to use the
Xamarin.Android project options to declare the default
HttpMessageHandler and TLS for the entire app. Then, if necessary,
programmatically instantiate Xamarin.Android.Net.AndroidClientHandler
objects. These options are described above.
The third option – using environment variables – is explained below.
Declare Environment Variables
There are two environment variables that are related to the use of TLS in Xamarin.Android:
XA_HTTP_CLIENT_HANDLER_TYPE – This environment variable
declares the default HttpMessageHandler that the application will
use. For example:
XA_HTTP_CLIENT_HANDLER_TYPE=Xamarin.Android.Net.AndroidClientHandler
XA_TLS_PROVIDER – This environment variable will declare
which TLS library will be used, either btls, legacy, or
default (which is the same as omitting this variable):
XA_TLS_PROVIDER=btls
This environment variable is set by adding an environment file to the
project. An environment file is a Unix-formatted plain-text file with a
build action of AndroidEnvironment:
Visual Studio
Visual Studio for Mac
Please see the Xamarin.Android Environment guide for more details about environment variables and Xamarin.Android.
Related Links
Transport Layer Security (TLS)