HttpWebRequest 類別

定義

命名空間:

System.Net

組件:

System.Net.Requests.dll

來源:

HttpWebRequest.cs

提供 WebRequest 類別的 HTTP 特定實作。

public ref class HttpWebRequest : System::Net::WebRequest, System::Runtime::Serialization::ISerializable

public class HttpWebRequest : System.Net.WebRequest, System.Runtime.Serialization.ISerializable

type HttpWebRequest = class
    inherit WebRequest
    interface ISerializable

Public Class HttpWebRequest
Inherits WebRequest
Implements ISerializable

繼承

Object

MarshalByRefObject

WebRequest

HttpWebRequest

實作

ISerializable

範例

下列程式代碼範例會為 URI http://www.contoso.com/建立 HttpWebRequest。

HttpWebRequest^ myReq = dynamic_cast<HttpWebRequest^>(WebRequest::Create( "http://www.contoso.com/" ));

HttpWebRequest myReq =
(HttpWebRequest)WebRequest.Create("http://www.contoso.com/");

Dim myReq As HttpWebRequest = _
    WebRequest.Create("http://www.contoso.com/")

備註

謹慎

WebRequest、HttpWebRequest、ServicePoint和 WebClient 已經過時，您不應該將它們用於新的開發。 請改用 HttpClient。

HttpWebRequest 類別支援 WebRequest 中定義的屬性和方法，以及可讓使用者使用 HTTP 直接與伺服器互動的其他屬性和方法。

請勿使用 HttpWebRequest 建構函式。 使用 WebRequest.Create 方法來初始化新的 HttpWebRequest 物件。 如果統一資源識別元 （URI） 的配置是 http:// 或 https://，Create 會傳回 HttpWebRequest 物件。

GetResponse 方法會向 RequestUri 屬性中指定的資源提出同步要求，並傳回包含回應物件的 HttpWebResponse。 您可以使用 GetResponseStream傳回的數據流來接收響應數據。 如果回應物件或回應數據流已關閉，則會沒收剩餘的數據。 當關閉回應對象或數據流時，剩餘的數據將會清空，而且套接字會在關閉回應對象或數據流時重複使用：這是保持運作或管線要求，只需要接收少量的數據，或剩餘的數據會以較小的時間間隔接收。 如果上述條件沒有保留或超過清空時間，將會關閉套接字。 對於保持運作或管線連線，我們強烈建議應用程式讀取數據流，直到 EOF 為止。 這可確保套接字將重新用於後續要求，進而產生更佳的效能和較少使用的資源。

當您想要將數據傳送至資源時，GetRequestStream 方法會傳回要用來傳送數據的 Stream 物件。 BeginGetRequestStream 和 EndGetRequestStream 方法會提供傳送數據流的異步存取。

若要使用 HttpWebRequest進行客戶端驗證，用戶端憑證必須安裝在目前使用者的 [我的證書存儲] 中。

當存取資源時發生錯誤時，HttpWebRequest 類別會擲回 WebException。 WebException.Status 屬性包含 WebExceptionStatus 值，指出錯誤的來源。 當 WebException.StatusWebExceptionStatus.ProtocolError時，Response 屬性會包含從資源接收的 HttpWebResponse。

HttpWebRequest 公開傳送至因特網資源的常見 HTTP 標頭值做為屬性、方法設定，或由系統設定;下表包含完整清單。 您可以將 Headers 屬性中的其他標頭設定為名稱/值組。 請注意，伺服器和快取可能會在要求期間變更或新增標頭。

下表列出由屬性或方法或系統設定的 HTTP 標頭。

頁眉	設定者
Accept	由 Accept 屬性設定。
Connection	由 Connection 屬性設定，KeepAlive 屬性。
Content-Length	由 ContentLength 屬性設定。
Content-Type	由 ContentType 屬性設定。
Expect	由 Expect 屬性設定。
Date	由系統設定為目前日期。
Host	由系統設定為目前的主機資訊。
If-Modified-Since	由 IfModifiedSince 屬性設定。
Range	由 AddRange 方法設定。
Referer	由 Referer 屬性設定。
Transfer-Encoding	由 TransferEncoding 屬性設定 （SendChunked 屬性必須 true]。
User-Agent	由 UserAgent 屬性設定。

注意

HttpWebRequest 會自動註冊。 您不需要先呼叫 RegisterPrefix 方法來註冊 System.Net.HttpWebRequest，再使用以 http:// 或 https://開頭的 URI。

本機電腦或應用程式組態檔可以指定使用預設 Proxy。 如果指定了 Proxy 屬性，則來自 Proxy 屬性的 Proxy 設定會覆寫本機計算機或應用程式組態檔，而 HttpWebRequest 實例會使用指定的 Proxy 設定。 如果未指定組態檔中的 Proxy，且未指定 Proxy 屬性，HttpWebRequest 類別會使用繼承自本機計算機上的因特網選項的 Proxy 設定。 如果因特網選項中沒有 Proxy 設定，則要求會直接傳送至伺服器。

注意

架構會在建立 SSL 工作階段時快取 SSL 工作階段，並盡可能嘗試重複使用新要求的快取會話。 嘗試重複使用 SSL 會話時，Framework 會使用 ClientCertificates 的第一個專案（如果有的話），或在 ClientCertificates 空白時嘗試重複使用匿名會話。

注意

基於安全性考慮，預設會停用 Cookie。 如果您想要使用 Cookie，請使用 CookieContainer 屬性來啟用 Cookie。

.NET Framework 4.6 包含新的安全性功能，可封鎖連線不安全的加密和哈希演算法。 透過 HTTPClient、HttpWebRequest、FTPClient、SmtpClient、SslStream 等 API 使用 TLS/SSL 的應用程式，以及以 .NET Framework 4.6 為目標的應用程式預設會取得更安全的行為。

開發人員可能會想要退出退出此行為，以維持與其現有 SSL3 服務或 TLS w/ RC4 服務的互操作性。 本文 說明如何修改程序代碼，以便停用新的行為。

建構函式

HttpWebRequest(SerializationInfo, StreamingContext)

已淘汰. 從 SerializationInfo 和 StreamingContext 類別的指定實例，初始化 HttpWebRequest 類別的新實例。 這個建構函式已經過時。

屬性

Accept	取得或設定 Accept HTTP 標頭的值。
Address	取得實際回應要求之因特網資源的統一資源標識碼（URI）。
AllowAutoRedirect	取得或設定值，指出要求是否應該遵循重新導向回應。
AllowReadStreamBuffering	取得或設定值，這個值表示是否要緩衝從因特網資源接收的 。
AllowWriteStreamBuffering	取得或設定值，這個值表示是否要緩衝傳送至因特網資源的數據。
AuthenticationLevel	取得或設定值，指出用於這個要求的驗證和模擬層級。 (繼承來源 WebRequest)
AutomaticDecompression	取得或設定所使用的解壓縮類型。
CachePolicy	取得或設定這個要求的快取原則。 (繼承來源 WebRequest)
ClientCertificates	取得或設定與此要求相關聯的安全性憑證集合。
Connection	取得或設定 Connection HTTP 標頭的值。
ConnectionGroupName	取得或設定要求的連接組名。
ContentLength	取得或設定 HTTP 標頭 Content-length。
ContentType	取得或設定 Content-type HTTP 標頭的值。
ContinueDelegate	取得或設定從因特網資源收到 HTTP 100 繼續回應時所呼叫的委派方法。
ContinueTimeout	取得或設定逾時，以毫秒為單位，等待從伺服器接收 100-Continue。
CookieContainer	取得或設定與要求相關聯的 Cookie。
CreatorInstance	在子代類別中覆寫時，取得衍生自用來建立 WebRequest 具現化之要求至指定 URI IWebRequestCreate 類別的 Factory 物件。 (繼承來源 WebRequest)
Credentials	取得或設定要求的驗證資訊。
Date	取得或設定 HTTP 要求中使用的 Date HTTP 標頭值。
DefaultCachePolicy	取得或設定這個要求的預設快取原則。
DefaultMaximumErrorResponseLength	取得或設定 HTTP 錯誤回應的預設最大長度。
DefaultMaximumResponseHeadersLength	取得或設定 MaximumResponseHeadersLength 屬性的預設值。
Expect	取得或設定 Expect HTTP 標頭的值。
HaveResponse	取得值，這個值表示是否已從因特網資源接收回應。
Headers	指定組成 HTTP 標頭的名稱/值組集合。
Host	取得或設定主機標頭值，以用於與要求 URI 無關的 HTTP 要求中。
IfModifiedSince	取得或設定 If-Modified-Since HTTP 標頭的值。
ImpersonationLevel	取得或設定目前要求的模擬層級。 (繼承來源 WebRequest)
KeepAlive	取得或設定值，這個值表示是否要對因特網資源建立持續性連線。
MaximumAutomaticRedirections	取得或設定要求所遵循的重新導向數目上限。
MaximumResponseHeadersLength	取得或設定回應標頭允許的最大長度。
MediaType	取得或設定要求的媒體類型。
Method	取得或設定要求的方法。
Pipelined	取得或設定值，這個值表示是否要將要求管線傳送至因特網資源。
PreAuthenticate	取得或設定值，這個值表示是否要使用要求傳送 Authorization 標頭。
ProtocolVersion	取得或設定要用於要求的 HTTP 版本。
Proxy	取得或設定要求的 Proxy 資訊。
ReadWriteTimeout	取得或設定寫入數據流或從數據流讀取時，以毫秒為單位的逾時。
Referer	取得或設定 Referer HTTP 標頭的值。
RequestUri	取得要求的原始統一資源標識碼 （URI）。
SendChunked	取得或設定值，這個值表示是否要將區段中的數據傳送至因特網資源。
ServerCertificateValidationCallback	取得或設定回呼函式，以驗證伺服器證書。
ServicePoint	取得要求所使用的服務點。
SupportsCookieContainer	取得值，這個值表示要求是否支援 CookieContainer。
Timeout	取得或設定 GetResponse() 和 GetRequestStream() 方法的逾時值，以毫秒為單位。
TransferEncoding	取得或設定 Transfer-encoding HTTP 標頭的值。
UnsafeAuthenticatedConnectionSharing	取得或設定值，這個值表示是否允許高速NTLM驗證的連線共用。
UseDefaultCredentials	取得或設定 Boolean 值，這個值會控制是否使用要求傳送默認認證。
UserAgent	取得或設定 User-agent HTTP 標頭的值。

方法

Abort()	取消對因特網資源的要求。
AddRange(Int32)	將位元組範圍標頭加入至要求數據開頭或結尾的特定範圍要求。
AddRange(Int32, Int32)	將位元組範圍標頭加入至指定範圍的要求。
AddRange(Int64)	將位元組範圍標頭加入至要求數據開頭或結尾的特定範圍要求。
AddRange(Int64, Int64)	將位元組範圍標頭加入至指定範圍的要求。
AddRange(String, Int32)	從所要求數據的開頭或結尾，將 Range 標頭加入至特定範圍的要求。
AddRange(String, Int32, Int32)	將範圍標頭加入至指定範圍的要求。
AddRange(String, Int64)	從所要求數據的開頭或結尾，將 Range 標頭加入至特定範圍的要求。
AddRange(String, Int64, Int64)	將範圍標頭加入至指定範圍的要求。
BeginGetRequestStream(AsyncCallback, Object)	開始異步要求，讓 Stream 對象用來寫入數據。
BeginGetResponse(AsyncCallback, Object)	開始對因特網資源的異步要求。
CreateObjRef(Type)	建立物件，其中包含產生用來與遠端物件通訊之 Proxy 所需的所有相關信息。 (繼承來源 MarshalByRefObject)
EndGetRequestStream(IAsyncResult)	結束異步要求，讓 Stream 對象用來寫入數據。
EndGetRequestStream(IAsyncResult, TransportContext)	結束異步要求，讓 Stream 對象用來寫入數據，並輸出與數據流相關聯的 TransportContext。
EndGetResponse(IAsyncResult)	結束對因特網資源的異步要求。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 擷取控制這個實例存留期原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetObjectData(SerializationInfo, StreamingContext)	已淘汰. 以串行化目標物件所需的數據填入 SerializationInfo。
GetRequestStream()	取得用來寫入要求數據的 Stream 物件。
GetRequestStream(TransportContext)	取得 Stream 物件，用來寫入要求數據，並輸出與數據流相關聯的 TransportContext。
GetRequestStreamAsync()	在子系類別中覆寫時，傳回 Stream，以異步操作方式將數據寫入因特網資源。 (繼承來源 WebRequest)
GetResponse()	從因特網資源傳回回應。
GetResponseAsync()	在子代類別中覆寫時，以異步操作的形式傳回因特網要求的回應。 (繼承來源 WebRequest)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已淘汰. 取得存留期服務物件，以控制這個實例的存留期原則。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立目前 MarshalByRefObject 對象的淺層複本。 (繼承來源 MarshalByRefObject)
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)

明確介面實作

ISerializable.GetObjectData(SerializationInfo, StreamingContext)

已淘汰. 以串行化目標物件所需的數據填入 SerializationInfo。

擴充方法

GetRequestMetadata(HttpWebRequest)	取得要用於遙測之傳出要求的元數據。
SetRequestMetadata(HttpWebRequest, RequestMetadata)	設定要用於遙測之傳出要求的元數據。

另請參閱

• DefaultProxy 元素 （網路設定）
• 3.5 SP1 版中 HTTPWebRequest 的 NTLM 驗證變更