HttpClient 類別

定義

命名空間:

Windows.Web.Http

傳送 HTTP 要求，並從 URI 所識別的資源接收 HTTP 回應。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。

public ref class HttpClient sealed : IClosable, IStringable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Web.Http.IHttpClientFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class HttpClient final : IClosable, IStringable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Web.Http.IHttpClientFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class HttpClient : System.IDisposable, IStringable

function HttpClient(filter)

Public NotInheritable Class HttpClient
Implements IDisposable, IStringable

繼承

Object Platform::Object IInspectable HttpClient

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

實作

IClosable IDisposable IStringable

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

下列範例程式代碼示範如何以字串的形式從 Web 伺服器取得內容。

using System;

var uri = new System.Uri("http://www.bing.com");
using (var httpClient = new Windows.Web.Http.HttpClient())
{
    // Always catch network exceptions for async methods
    try
    {
        string result = await httpClient.GetStringAsync(uri);
    }
    catch (Exception ex)
    {
        // Details in ex.Message and ex.HResult.
    }
}
// Having exited the scope of the using statement, httpClient.Dispose() will be called
// automatically, thus freeing up system resources (the underlying socket, and memory
// used for the object).

#include "winrt/Windows.Foundation.h"
#include "winrt/Windows.Web.Http.h"
using namespace winrt;

Windows::Foundation::IAsyncAction HttpClientExample()
{
    Windows::Foundation::Uri uri{ L"http://www.bing.com" };
    Windows::Web::Http::HttpClient httpClient{};

    // Always catch network exceptions for async methods
    try
    {
        auto response{ co_await httpClient.GetStringAsync(uri) };
    }
    catch (winrt::hresult_error const& ex)
    {
        // Details in ex.message() and ex.to_abi().
    }

    // The destructor of HttpClient frees system resources
    // (the underlying socket, and memory used for the object).
}

using namespace Windows::Foundation;
using namespace Windows::Web::Http;

uri = ref new Uri("http://example.com/datalist.aspx");
httpClient = ref new HttpClient();

// Always catch network exceptions for async methods
try 
{
    httpClient->GetStringAsync(uri);
}
catch 
{
    // Details in ex.Message and ex.HResult.   
}

// In C++/CX, the system resources used by httpClient object are released 
// when the object falls out of scope or by the destructor (delete operator).

應用程式通常會使用 HttpClient 類別來下載並剖析文字。 HTTP 伺服器在 Content-Type 標頭中指定的字元編碼可能不符合 HTTP 回應本文的字元編碼， (XML 檔中的 XML 編碼，例如) 。 搭配文字使用 HttpClient 的其中一種方式是呼叫 GetStringAsync 方法，並將傳回的字串傳遞至文字剖析器。 不過，如果 Content-Type 不是字串可表示的類型，這可能會導致錯誤。 搭配 XML 剖析器使用 HttpClient 的可靠方式是呼叫 GetBufferAsync 方法，並剖析 “<？xml>” 專案的緩衝區。 然後使用指定的字元編碼 (“<xmlversion=”1.0“ encoding=”UTF-8“？>”，例如) 來剖析 HTTP 回應本文。 對於其他文字格式，可以使用類似的方法，其中應用程式會掃描 HTTP 回應本文的初始部分，以判斷所使用的字元編碼方式。

備註

HttpClient 類別實例可作為傳送 HTTP 要求和接收回應的會話。 HttpClient 實例是套用至該實例所執行之所有要求的設定集合。 此外，每個 HttpClient 實例都會使用自己的連線集區，將其要求與其他 HttpClient 實例所執行的要求隔離。

HttpClient 也可做為類別，以搭配篩選條件使用，以供更特定的 HTTP 用戶端使用。 例如，HttpClientFilter 會在 GetFriends 方法 (提供社交網路服務特定的其他方法，例如) 。

如果在 Windows.Web.Http 命名空間中使用 HttpClient 和相關類別的應用程式下載大量數據， (50 MB 以上的) ，則應用程式應該串流處理這些下載，而不使用默認緩衝。 如果使用默認緩衝，則用戶端記憶體使用量會變得非常大，可能會導致效能降低。

如需 C# 和 C++/WinRT 中的範例程式代碼，示範如何使用 HttpClient 連線到 HTTP 伺服器，請參閱 HttpClient。

如需 JavaScript 和 HTML 中示範如何使用 HttpClient 連線到 HTTP 伺服器的範例程式代碼，請參閱 使用 Windows.Web.Http 連線到 HTTP 伺服器。

版本歷程記錄

Windows 版本	SDK 版本	新增值
1903	18362	TryDeleteAsync
1903	18362	TryGetAsync (Uri)
1903	18362	TryGetAsync (Uri，HttpCompletionOption)
1903	18362	TryGetBufferAsync
1903	18362	TryGetInputStreamAsync
1903	18362	TryGetStringAsync
1903	18362	TryPostAsync
1903	18362	TryPutAsync
1903	18362	TrySendRequestAsync (HttpRequestMessage)
1903	18362	TrySendRequestAsync (HttpRequestMessage，HttpCompletionOption)

建構函式

HttpClient()	初始化 HttpClient 類別的新實例。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
HttpClient(IHttpFilter)	使用處理 HTTP 回應消息的特定篩選，初始化 HttpClient 類別的新實例。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。

屬性

DefaultPrivacyAnnotation	傳送 HTTP 要求，並從 URI 所識別的資源接收 HTTP 回應。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
DefaultRequestHeaders	取得應該隨每個要求一起傳送的標頭集合。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。

方法

Close()	關閉 HttpClient 實例並釋放已配置的資源。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
DeleteAsync(Uri)	將 DELETE 要求以異步操作的形式傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
Dispose()	執行與釋放 (Free)、釋放 (Release) 或重設 Unmanaged 資源相關聯之應用程式定義的工作。
GetAsync(Uri)	以非同步作業的方式，將 GET 要求傳送至指定的 URI。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
GetAsync(Uri, HttpCompletionOption)	使用 HTTP 完成選項作為異步操作，將 GET 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
GetBufferAsync(Uri)	將 GET 要求傳送至指定的 Uri，並在異步操作中以緩衝區的形式傳回回應本文。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
GetInputStreamAsync(Uri)	將 GET 要求傳送至指定的 Uri ，並在異步操作中以數據流的形式傳回回應本文。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
GetStringAsync(Uri)	將 GET 要求傳送至指定的 URI，並透過非同步作業，以字串形式傳回回應內容。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
PostAsync(Uri, IHttpContent)	將POST要求以異步操作的形式傳送至指定的URI。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
PutAsync(Uri, IHttpContent)	以非同步作業的方式，將 PUT 要求傳送至指定的 URI。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
SendRequestAsync(HttpRequestMessage)	以非同步作業的方式，傳送 HTTP 要求。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
SendRequestAsync(HttpRequestMessage, HttpCompletionOption)	以 HTTP 完成選項作為異步操作傳送 HTTP 要求。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
ToString()	傳回表示目前 HttpClient 物件的字串。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryDeleteAsync(Uri)	將 DELETE 要求以異步操作的形式傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryGetAsync(Uri)	以異步操作的形式，將 GET 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryGetAsync(Uri, HttpCompletionOption)	以異步操作的形式，將 GET 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryGetBufferAsync(Uri)	將 GET 要求傳送至指定的 Uri，並以異步操作中的 IBuffer 值傳回回應本文做為 HttpGetBufferResult 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryGetInputStreamAsync(Uri)	將 GET 要求傳送至指定的 Uri ，並在異步操作中以數據流的形式傳回回應本文。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryGetStringAsync(Uri)	將 GET 要求傳送至指定的 URI，並透過非同步作業，以字串形式傳回回應內容。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryPostAsync(Uri, IHttpContent)	以異步操作的形式，將POST要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TryPutAsync(Uri, IHttpContent)	以異步操作的形式，將 PUT 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TrySendRequestAsync(HttpRequestMessage)	以異步操作的形式，將 HTTP 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。
TrySendRequestAsync(HttpRequestMessage, HttpCompletionOption)	以異步操作的方式，將具有完成選項的 HTTP 要求傳送至指定的 URI 。 如需 HttpClient 類別的程式設計指引和程式代碼範例，請參閱 HttpClient 概念性主題。

另請參閱

• IClosable
• IStringable
• Uri
• Windows.Web.Http
• Windows.Web.Http.Filters
• Windows.Web.Http.Headers
• HttpClient
• 使用 Windows.Web.Http 連線到 HTTP 伺服器
• 處理網路應用程式中的例外狀況
• System.Uri
• 背景傳輸範例
• 背景傳輸範例 (Windows 8.x)
• HttpClient 範例 (Windows 10)
• JSON 範例 (Windows 10)