衍生自 WebRequest

WebRequest 類別是抽象基底類別，可提供基本的方法和屬性，以建立適合 .NET Framework 可外掛式通訊協定 (Protocol) 模型的特定通訊協定要求處理常式。使用 WebRequest 類別的應用程式，可利用任何支援的通訊協定來要求資料，不需要指定所使用的通訊協定。

要將特定通訊協定類別作為可外掛式通訊協定使用，必須符合兩項準則：類別必須實作 IWebRequestCreate 介面，並且必須以 WebRequest.RegisterPrefix 方法註冊。類別必須覆寫所有 WebRequest 的抽象方法和屬性，以提供可外掛的介面。

WebRequest 執行個體 (Instance) 只能用一次；如果您要提出其他要求，應建立新的 WebRequest。WebRequest 支援以 ISerializable 介面讓開發人員能夠將樣板 WebRequest 序列化，並重建其他要求的樣板 (Template)。

IWebRequest 建立方法

Create 方法負責初始化特定通訊協定類別的新執行個體。當建立新的 WebRequest 時，WebRequest.Create 方法會將所要求的 URI 與以 RegisterPrefix 方法註冊的 URI 前置詞配對。正確的特定通訊協定子代 (Descendant) 的 Create 方法必須傳回子代的初始化執行個體，這個子代不須修改任何特定通訊協定欄位，便能夠執行通訊協定標準的要求/回應交易。

ConnectionGroupName 屬性

ConnectionGroupName 屬性用來命名資源的一組連接，如此一來就可在單一連接上提出多個要求。若要實作連接共用，必須使用共用和指派連接的特定通訊協定方法。例如，所提供的 ServicePointManager 類別實作 HttpWebRequest 類別的連接共用。ServicePointManager 類別建立 ServicePoint，以連接到每一連接群組的特定伺服器。

ContentLength 屬性

ContentLength 屬性指定上載資料時將傳送至伺服器的資料位元組數。

通常 Method 屬性必須設定為指示當 ContentLength 屬性設定為大於零的值時，上載正在進行中。

ContentType 屬性

ContentType 屬性 提供通訊協定要求您傳送至伺服器的特殊資訊，以辨識正在傳送的內容型別。通常這是任何上載資料的 MIME 內容型別。

Credentials 屬性

Credentials 屬性包含驗證伺服器要求所需的資訊。您必須實作您通訊協定驗證 (Authentication) 處理的詳細資訊。AuthenticationManager 類別負責驗證要求並提供驗證 Token。提供通訊協定所使用之認證的類別，必須實作 ICredentials 介面。

Headers 屬性

Headers 屬性包含與要求有關的中繼資料 (Metadata) 名稱值配對的任意集合。能夠表示為名稱值配對的通訊協定所需的中繼資料，都可以包含在 Headers 屬性之內。通常這個資訊必須在呼叫 GetRequestStream 或 GetResponse 方法之前加以設定；一旦提出要求，中繼資料就會視為唯讀。

您不需要使用 Headers 屬性就可以使用頁首中繼資料。特定通訊協定中繼資料可公開為屬性；例如 HttpWebRequest.UserAgent 屬性公開 User-Agent HTTP 標頭。當您將標頭中繼資料公開為屬性時，您就不能再使用 Header 屬性來設定相同的屬性。

Method 屬性

Method 屬性包含要求要伺服器執行的動作。Method 屬性的預設值必須啟用標準要求/回應動作，且不需要設定任何特定通訊協定屬性。例如，HttpWebResponse 方法預設為 GET，它要求 Web 伺服器的資源並傳回回應。

通常，當 Method 屬性設定為指示正在上載的動作 (Verb 或 Action) 時，ContentLength 屬性必須設定為大於零的值。

PreAuthenticate 屬性

應用程式將 PreAuthenticate 屬性設定為指示驗證資訊應與初始要求一起傳送，而不是在等待驗證的挑戰。PreAuthenticate 屬性只有在通訊協定支援與初始要求一起傳送的驗證認證時才有意義。

Proxy 屬性

Proxy 屬性包含 IWebProxy 介面，可用來存取所要求的資源。Proxy 屬性只有在通訊協定支援代理的要求時才有意義。如果您的通訊協定要求預設的 Proxy 時，您就必須要設定。

在某些環境下，例如在企業防火牆之後，您的通訊協定可能必須要使用 Proxy。在這種情況下，您必須實作 IWebProxy 介面來建立您通訊協定所使用的 Proxy 類別。

RequestUri 屬性

RequestUri 屬性包含傳遞至 WebRequest.Create 方法的 URI。WebRequest 一旦建立好，就是唯讀且無法變更。如果您的通訊協定支援重新導向，回應可來自由不同 URI 所辨識的資源。如果您要提供存取給回應的 URI，就必須提供包含那個 URI 的其他屬性。

Timeout 屬性

Timeout 屬性包含在要求時間結束且擲回例外狀況 (Exception) 之前等待的時間長度，以毫秒為單位。Timeout 僅適用 GetResponse 方法所提出的同步化要求；非同步的 (Asynchronous) 要求必須使用 Abort 方法來取消暫止要求。

設定 Timeout 屬性只有在特定通訊協定類別實作逾時處理時才有意義。

Abort 方法

Abort 方法能夠取消伺服器的暫止非同步要求。取消要求後，呼叫 GetResponse、BeginGetResponse、EndGetResponse、GetRequestStream、BeginGetRequestStream 或 EndGetRequestStream，將擲回 Status 屬性設定為 RequestCanceled 的 WebException。

BeginGetRequestStream 和 EndGetRequestStream 方法

BeginGetRequestStream 方法針對用來上載資料至伺服器的資料流，啟動非同步要求。EndGetRequestStream 方法完成非同步要求並傳回所要求的資料流。這些方法使用標準的 .NET Framework 非同步模式，實作 GetRequestStream 方法。

BeginGetResponse 和 EndGetResponse 方法

BeginGetResponse 方法啟動對伺服器的非同步要求。EndGetResponse 方法完成非同步要求並傳回所要求的回應。這些方法使用標準的 .NET Framework 非同步模式，實作 GetResponse 方法。

GetRequestStream 方法

GetRequestStream 方法傳回將資料寫入所要求伺服器的資料流。傳回的資料流應該是不會進行搜尋的唯寫資料流；它可以是寫入伺服器之資料的單向資料流。這個資料流針對 CanRead 和 CanSeek 屬性傳回 False，針對 CanWrite 屬性傳回 True。

GetRequestStream 方法通常開啟對伺服器的連接，並在傳回資料流之前，傳送指示資料正被傳送至伺服器的標頭資訊。由於是 GetRequestStream 開始這項要求的，因此在呼叫 GetRequestStream 之後通常不允許設定 Header 屬性或 ContentLength 屬性。

GetResponse 方法

GetResponse 方法會傳回代表伺服器回應之 WebResponse 類別的特定通訊協定子代。除非要求已由 GetRequestStream 方法啟始，不然 GetResponse 方法就會建立連接至 RequestUri 所辨識的資源、傳送指示所提出要求類型的標頭資訊，接著並收到資源的回應。

一旦呼叫 GetResponse 方法，所有屬性都應視為唯讀。WebRequest 執行個體只能用一次；如果您要提出其他要求，應建立新的 WebRequest。

GetResponse 方法負責建立適當的 WebResponse 子代以包含內送回應。

請參閱

設計可外掛式通訊協定程式 | 衍生自 WebResponse | WebRequest 類別 | HttpWebRequest 類別 | FileWebRequest 類別