ASP.NET Web API 心得筆記 (9) 簡介 System.Net.Http.HttpClient 類別

HttpClient 類別介紹

提供基礎類別來傳送 HTTP requests(請求)和接收 HTTP responses(回應)從一個 URI 的資源定義。目前 HttpClient 類別為 .NET Framework 4.5 Beta 中 System.Net.Http 命名空間之下，使用方式在未來正式版中可能會有修改，以下所提範例在未來是否能正常運作是未知，但提供的觀念我相信是一樣的。

HttpClient 類別使用說明

HttpClient 類別執行個體做為發送的 HTTP 請求的會話(session)，HttpClient 執行個體是應用於該執行個體來執行所有請求的設定的集合。此外，每一個 HttpClient 執行個體將使用自己的連接池(connection pool)，以隔離來自其他 HttpClient 執行個體所執行的請求的請求。

使用 HttpClient 類別非同步取得 URI 資源

我們先看一個最簡單的範例，我們開一個【主控台應用程式】：

Imports System.Net.Http

Module Module1

    ''' <summary>
    ''' 使用 HttpClient 送出非同步請求，取得 URI 資源
    ''' </summary>
    ''' <remarks></remarks>
    Async Sub GetCountries()
        Dim client As New HttpClient()

        ' 送出非同步請求(GET)
        Dim response As HttpResponseMessage = Await client.GetAsync("http://api.worldbank.org/countries?format=json")
        response.EnsureSuccessStatusCode()

        ' 非同步取得 HTTP Content
        Dim content As String = Await response.Content.ReadAsStringAsync()

        Console.WriteLine(content)
    End Sub

    Sub Main()
        Try
            GetCountries()
        Catch ex As HttpRequestException
            Console.WriteLine("錯誤: {0}", ex.Message)
        End Try

        Console.ReadLine()
    End Sub

End Module

Async 與 Await 是 Visual Studio Asynchronous Programming 所提供的功能，在 Visual Studio 2010 中必須安裝擴充程式才能使用，Visual Studio 11 中直接內建支援。Async 是宣告此此函式是非同步函式，Await 是呼叫非同步方法。透過 GetAsync() 送出非同步請求。看一下 GetAsync() 其中一個宣告：

Public Function GetAsync (requestUri As String) _
As Task(Of HttpResponseMessage)

GetAsync() 能向指定的 URI 傳送非同步 GET 請求，它會回傳 HttpResponseMessage 類別。HttpResponseMessage 類別用來表示 HTTP 回應訊息，透過 Content 屬性來取得或設定 HTTP 回應訊息，看一下 Content 屬性宣告：

Public Property Content As HttpContent

Content 屬性本身是個 HttpContent 類別，它提供了數個非同步取得 HTTP 內容的方法，如 ReadAsByteArrayAsync()、ReadAsStreamAsync()、ReadAsStringAsync()等，我們使用了 ReadAsStringAsync() 將非同步的 HTTP 內容寫入字串(String)。最後輸出取得內容。

執行過程，你能發現先是一片空白(非同步操作中)，需等一會兒，然後才顯示取得 URI 資源內容。

自訂 HttpClient 類別所傳送的 Http Header

我們新增一個 CustomUserAgent 類別，然後繼承 HttpClientHandler 抽象類別覆寫 SendAsync() 方法：

''' <summary>
''' 自訂 HTTP Header
''' </summary>
Class CustomUserAgent
    Inherits HttpClientHandler

    Protected Overrides Function SendAsync(request As HttpRequestMessage,
                                           cancellationToken As Threading.CancellationToken) _
                                           As Task(Of HttpResponseMessage)

        ' 設定 Referrer
        request.Headers.Referrer = New Uri("http://blog.kkbruce.net")
        ' 新增 UserAgent
        request.Headers.Add("UserAgent", "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 Safari/536.5")

        Return MyBase.SendAsync(request, cancellationToken)
    End Function
End Class

我們在前一篇 DelegatingHandler 部分提過 delegator pattern(代理者模式)一樣, 透過此模式的設計，讓我們可以很簡易就可以攔截 HttpClient 的輸入和輸出，進行實作一些自訂的動作。接下來我們自訂一個非同步函式：

''' <summary>
''' 使用 HttpClient 送出非同步請求，取得 URI 資源
''' </summary>
Async Sub GetCountriesCustomHeader()
    ' 使用自訂 Header
    Dim client As New HttpClient(New CustomUserAgent)

    ' 送出非同步請求(GET)
    Dim response As HttpResponseMessage = Await client.GetAsync("http://api.worldbank.org/countries?format=json")
    response.EnsureSuccessStatusCode()

    ' 非同步取得 HTTP Content
    Dim content As String = Await response.Content.ReadAsStringAsync()

    Console.WriteLine(content)
End Sub

用法非常簡單，只需要把我們自訂的 CustomUserAgent 類別傳入 HttpClient 的建構式即可，這樣就算是【主控台應用程式】也能發出和瀏覽器一樣的 UserAgent 給提供服務網站。

HttpClient 類別 Post, Put, Delete非同步方法

在 HttpClient 類別中，還能看到 PostAsync()、PutAsync()、DeleteAsync()等方法，Get / Post / Put / Delete 這四個詞有沒有好熟悉的感覺。

PostAsync()

使用非同步操作傳送一個 POST 請求到指定的 URI。

PutAsync()

使用非同步操作傳送一個 PUTt 請求到指定的 URI。

DeleteAsync()

使用非同步操作傳送一個 DELETE 請求到指定的 URI。

這也是我們會在 Web API 裡特別一章介紹 HttpClient 類別的原因，使用 HttpClient 類別的幫忙，我們能快速開發出支援非同步的 HTTP 用戶端，而且完整支援 GET / POST / PUT / DELETE，而提供服務者(即程式中的 URI)你可以選擇 Web API Framework。

參考資源

1. http://data.worldbank.org/querybuilder
2. HttpClient 類別
3. System.Net.Http 命名空間
4. Visual Studio Asynchronous Programming