適用於 Android 的 HttpClient 堆疊和 SSL/TLS 實作選取器

發行項
03/11/2024

HttpClient Stack 和 SSL/TLS 實作選取器會決定 Xamarin.Android 應用程式將使用的 HttpClient 和 SSL/TLS 實作。

項目必須參考 System.Net.Http 元件。

警告

2018 年 4 月 – 由於安全性需求增加，包括 PCI 合規性、主要雲端提供者和網頁伺服器，預計將停止支援 1.2 之前的 TLS 版本。在舊版Visual Studio中建立的 Xamarin 項目預設為使用舊版 TLS。

為了確保您的應用程式能夠繼續使用這些伺服器和服務， 您應該使用如下所示的 Android HttpClient 和 Native TLS 1.2 設定來更新 Xamarin 專案，然後將您的應用程式 重新建置並重新部署到您的使用者。

Visual Studio
Visual Studio for Mac

Xamarin.Android HttpClient 組態位於 [項目選項 Android 選項] 中，然後按兩下 [進階選項] 按鈕。>

以下是 TLS 1.2 支持的建議設定：

替代組態選項

AndroidClientHandler

AndroidClientHandler 是委派給原生 Java/OS 程式代碼，而不是在 Managed 程式代碼中實作所有專案的新處理程式。 這是建議的選項。

優點

使用原生 API 以提升效能和較小的可執行檔大小。
支援最新的標準，例如 TLS 1.2。

缺點

需要 Android 4.1 或更新版本。
某些 HttpClient 功能/選項無法使用。

Managed （HttpClientHandler）

Managed 處理程式是隨附於先前 Xamarin.Android 版本的完整受控 HttpClient 處理程式。

優點

它是與 MS .NET 和舊版 Xamarin 最相容的（功能）。

缺點

它未與 OS 完全整合（例如限制為 TLS 1.0）。
通常比原生 API 慢得多（例如加密）。
其需要更多 Managed 程式代碼，以建立較大的應用程式。

選擇處理程式

和 HttpClientHandler 之間的AndroidClientHandler選擇取決於應用程式的需求。 AndroidClientHandler 建議使用最新的安全性支援，例如

您需要 TLS 1.2+ 支援。
您的應用程式是以Android 4.1（API 16）或更新版本為目標。
您需要 TLS HttpClient1.2+ 支援。
您不需要 TLS WebClient1.2+ 支援。

HttpClientHandler 如果您需要 TLS 1.2+ 支援，但必須支援 Android 4.1 之前的 Android 版本，則是不錯的選擇。如果您需要 TLS 1.2+ 支援， WebClient這也是不錯的選擇。

從 Xamarin.Android 8.3 開始， HttpClientHandler 預設為 Boring SSL （btls）作為基礎 TLS 提供者。無聊 SSL TLS 提供者提供下列優點：

它支援 TLS 1.2+。
它支援所有 Android 版本。
它提供和WebClient的 HttpClient TLS 1.2+ 支援。

使用無聊 SSL 作為 TLS 提供者的缺點是，它可以增加產生的 APK 大小（它會為每個支援的 ABI 增加大約 1 MB 的額外 APK 大小）。

從 Xamarin.Android 8.3 開始，預設的 TLS 提供者是無聊 SSL （btls）。如果您不想使用無聊 SSL，您可以將屬性設定$(AndroidTlsProvider)為來還原為歷史管理的 SSL 實作（如需設定組建屬性的詳細資訊，請參閱建置程式）。legacy

以程序設計方式使用 `AndroidClientHandler`

Xamarin.Android.Net.AndroidClientHandler是HttpMessageHandler特別針對 Xamarin.Android 的實作。此類別的實例會針對所有 HTTP 連線使用原生 java.net.URLConnection 實作。理論上，這會增加 HTTP 效能和較小的 APK 大小。

此代碼段是如何明確針對類別之單一實例的 HttpClient 範例：

// Android 4.1 or higher, Xamarin.Android 6.1 or higher
HttpClient client = new HttpClient(new Xamarin.Android.Net.AndroidClientHandler ());

注意

基礎 Android 裝置必須支援 TLS 1.2（即。Android 4.1 和更新版本）。請注意，TLS 1.2 的官方支援是在 Android 5.0+ 中。不過，某些裝置支援 Android 4.1+ 中的 TLS 1.2。

SSL/TLS 實作建置選項

這個項目選項可控制所有 Web 要求都會使用哪些基礎 TLS 連結庫，以及 HttpClientWebRequest。根據預設，會選取 TLS 1.2：

Visual Studio
Visual Studio for Mac

例如：

var client = new HttpClient();

如果 HttpClient 實作設定為 Managed ，且 TLS 實作設定 為 Native TLS 1.2+，則 client 物件會自動使用 Managed HttpClientHandler 和 TLS 1.2 （BoringSSL 連結庫提供）來要求 HTTP 要求。

不過，如果 HttpClient 實 作設定為 AndroidHttpClient，則所有 HttpClient 物件都會使用基礎 Java 類別 java.net.URLConnection ，而且不會受到 TLS/SSL 實 作值影響。 WebRequest 物件會使用 BoringSSL 連結庫。

控制 SSL/TLS 組態的其他方式

Xamarin.Android 應用程式有三種方式可以控制 TLS 設定：

在 [項目選項] 中選取 HttpClient 實作和預設 TLS 連結庫。
以程式設計方式使用 Xamarin.Android.Net.AndroidClientHandler。
宣告環境變數（選擇性）。

在三個選項中，建議的方法是使用 Xamarin.Android 專案選項來宣告整個應用程式的預設 HttpMessageHandler 和 TLS。然後，如有必要，以程序設計方式具現化 Xamarin.Android.Net.AndroidClientHandler 物件。上述說明這些選項。

使用環境變數的第三個選項如下所述。

宣告環境變數

Xamarin.Android 中使用 TLS 有兩個環境變數：

XA_HTTP_CLIENT_HANDLER_TYPE – 此環境變數會宣告應用程式將使用的預設值 HttpMessageHandler 。例如：
```
XA_HTTP_CLIENT_HANDLER_TYPE=Xamarin.Android.Net.AndroidClientHandler
```
XA_TLS_PROVIDER – 此環境變數會宣告將使用哪一個 TLS 連結庫、 btls、 legacy或 default （與省略此變數相同）：
```
XA_TLS_PROVIDER=btls
```