WebClient 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
提供從 URI 所識別的資源中，傳送與接收資料的常見方法。
public ref class WebClient : System::ComponentModel::Componentpublic ref class WebClient sealed : System::ComponentModel::Componentpublic class WebClient : System.ComponentModel.Component[System.Runtime.InteropServices.ComVisible(true)]
public sealed class WebClient : System.ComponentModel.Component[System.Runtime.InteropServices.ComVisible(true)]
public class WebClient : System.ComponentModel.Componenttype WebClient = class
inherit Component[<System.Runtime.InteropServices.ComVisible(true)>]
type WebClient = class
inherit ComponentPublic Class WebClient
Inherits ComponentPublic NotInheritable Class WebClient
Inherits Component- 繼承
- 屬性
範例
下列程式碼範例會採用資源的 URI、擷取它，並顯示回應。
#using <System.dll>
using namespace System;
using namespace System::Net;
using namespace System::IO;
int main()
{
array<String^>^args = Environment::GetCommandLineArgs();
if ( args == nullptr || args->Length == 1 )
{
throw gcnew ApplicationException( "Specify the URI of the resource to retrieve." );
}
WebClient^ client = gcnew WebClient;
// Add a user agent header in case the
// requested URI contains a query.
client->Headers->Add( "user-agent", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)" );
Stream^ data = client->OpenRead( args[ 1 ] );
StreamReader^ reader = gcnew StreamReader( data );
String^ s = reader->ReadToEnd();
Console::WriteLine( s );
data->Close();
reader->Close();
}
using System;
using System.Net;
using System.IO;
public class Test
{
public static void Main (string[] args)
{
if (args == null || args.Length == 0)
{
throw new ApplicationException ("Specify the URI of the resource to retrieve.");
}
WebClient client = new WebClient ();
// Add a user agent header in case the
// requested URI contains a query.
client.Headers.Add ("user-agent", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)");
Stream data = client.OpenRead (args[0]);
StreamReader reader = new StreamReader (data);
string s = reader.ReadToEnd ();
Console.WriteLine (s);
data.Close ();
reader.Close ();
}
}
Imports System.Net
Imports System.IO
Public Class Test
Public Shared Sub Main(args() As String)
If args Is Nothing OrElse args.Length = 0 Then
Throw New ApplicationException("Specify the URI of the resource to retrieve.")
End If
Dim client As New WebClient()
' Add a user agent header in case the
' requested URI contains a query.
client.Headers.Add("user-agent", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.2; .NET CLR 1.0.3705;)")
Dim data As Stream = client.OpenRead(args(0))
Dim reader As New StreamReader(data)
Dim s As String = reader.ReadToEnd()
Console.WriteLine(s)
data.Close()
reader.Close()
End Sub
End Class
備註
重要
不建議您將 類別用於 WebClient 新的開發。 請改用 System.Net.Http.HttpClient 類別。
類別 WebClient 提供一般方法，可用來將資料傳送至 URI 所識別的任何本機、內部網路或網際網路資源或接收資料。
類別 WebClient 會 WebRequest 使用 類別來提供資源的存取權。 WebClient實例可以使用方法註冊 WebRequest.RegisterPrefix 的任何 WebRequest 子系來存取資料。
注意
根據預設，.NET Framework支援以 http: 、 https: 、 ftp: 和 file: 配置識別碼開頭的 URI。
下表描述 WebClient 將資料上傳至資源的方法。
| 方法 | 描述 |
|---|---|
| OpenWrite | 擷 Stream 取用來將資料傳送至資源的 。 |
| OpenWriteAsync | 擷 Stream 取用來將資料傳送至資源的 ，而不會封鎖呼叫執行緒。 |
| UploadData | 將位元組陣列傳送至資源，並傳回包含任何回應的 Byte 陣列。 |
| UploadDataAsync | Byte將陣列傳送至資源，而不封鎖呼叫執行緒。 |
| UploadFile | 將本機檔案傳送至資源，並傳回包含任何回應的 Byte 陣列。 |
| UploadFileAsync | 將本機檔案傳送至資源，而不封鎖呼叫執行緒。 |
| UploadValues | NameValueCollection將 傳送至資源，並傳回包含任何回應的 Byte 陣列。 |
| UploadValuesAsync | NameValueCollection將 傳送至資源，並傳回 Byte 包含任何回應的陣列，而不會封鎖呼叫執行緒。 |
| UploadString | String將 傳送至資源，並傳回包含任何回應的 String 。 |
| UploadStringAsync | String將 傳送至資源，而不封鎖呼叫執行緒。 |
下表說明 WebClient 從資源下載資料的方法。
| 方法 | 描述 |
|---|---|
| OpenRead | 從資源傳回資料做為 Stream 。 |
| OpenReadAsync | 從資源傳回資料，而不封鎖呼叫執行緒。 |
| DownloadData | 從資源下載資料並傳 Byte 回陣列。 |
| DownloadDataAsync | 從資源下載資料並傳回 Byte 陣列，而不會封鎖呼叫執行緒。 |
| DownloadFile | 將資料從資源下載到本機檔案。 |
| DownloadFileAsync | 將資料從資源下載到本機檔案，而不會封鎖呼叫執行緒。 |
| DownloadString | String從資源下載 ，並傳 String 回 。 |
| DownloadStringAsync | String從資源下載 ，而不封鎖呼叫執行緒。 |
您可以使用 CancelAsync 方法來嘗試取消非同步作業。
實例 WebClient 預設不會傳送選擇性 HTTP 標頭。 如果您的要求需要選擇性標頭，您必須將標頭新增至 Headers 集合。 例如，若要在回應中保留查詢，您必須新增使用者代理程式標頭。 此外，如果缺少使用者代理程式標頭，伺服器可能會傳回 500 (內部伺服器錯誤) 。
AllowAutoRedirect 設定為 true 實例中的 WebClient 。
給繼承者的注意事項
衍生類別應該呼叫 的基類實 WebClient 作，以確保衍生類別如預期般運作。
建構函式
| WebClient() |
已過時。
初始化 WebClient 類別的新執行個體。 |
屬性
| AllowReadStreamBuffering |
已過時。
取得或設定值，這個值表示是否要為 WebClient 執行個體緩衝處理從網際網路資源讀取的資料。 |
| AllowWriteStreamBuffering |
已過時。
取得或設定值，這個值表示是否要為 WebClient 執行個體緩衝處理寫入網際網路資源的資料。 |
| BaseAddress |
取得或設定由 WebClient 要求的基底 URI。 |
| CachePolicy |
取得或設定應用程式的快取原則，用於這個 WebClient 執行個體使用 WebRequest 物件取得的任何資源。 |
| CanRaiseEvents |
取得值，指出元件是否能引發事件。 (繼承來源 Component) |
| Container |
取得包含 IContainer 的 Component。 (繼承來源 Component) |
| Credentials |
取得或設定傳送至主機並用於驗證要求的網路認證。 |
| DesignMode |
取得值，指出 Component 目前是否處於設計模式。 (繼承來源 Component) |
| Encoding |
取得或設定用來上傳和下載字串的 Encoding。 |
| Events |
取得附加在這個 Component 上的事件處理常式清單。 (繼承來源 Component) |
| Headers |
取得或設定與要求相關聯標頭名稱/值組合的集合。 |
| IsBusy |
取得 Web 要求是否仍在進行中的資訊。 |
| Proxy |
取得或設定這個 WebClient 物件使用的 Proxy。 |
| QueryString |
取得或設定與要求相關的查詢名稱/值組合的集合。 |
| ResponseHeaders |
取得與回應相關聯標頭名稱/值組的集合。 |
| Site | (繼承來源 Component) |
| UseDefaultCredentials |
取得或設定 Boolean 值，控制是否隨著要求傳送 DefaultCredentials。 |
方法
事件
| Disposed |
當 Dispose() 方法的呼叫處置元件時，就會發生。 (繼承來源 Component) |
| DownloadDataCompleted |
在非同步資料下載作業完成時發生。 |
| DownloadFileCompleted |
在非同步檔案下載作業完成時發生。 |
| DownloadProgressChanged |
在非同步下載作業成功傳輸部分或全部資料時發生。 |
| DownloadStringCompleted |
在非同步資源下載作業完成時發生。 |
| OpenReadCompleted |
在開啟包含資源之資料流的非同步作業完成時發生。 |
| OpenWriteCompleted |
在開啟資料流以將資料寫入資源的非同步作業完成時發生。 |
| UploadDataCompleted |
在非同步資料上載作業完成時發生。 |
| UploadFileCompleted |
在非同步檔案上載作業完成時發生。 |
| UploadProgressChanged |
在非同步上傳作業成功傳輸部分或全部資料時發生。 |
| UploadStringCompleted |
在非同步字串上傳作業完成時發生。 |
| UploadValuesCompleted |
在名稱/值集合的非同步上載完成時發生。 |
| WriteStreamClosed |
已過時。
在使用寫入資料流以將資料寫入資源的非同步作業已關閉時發生。 |