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();
delete client;
}
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.");
}
using 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;)");
using Stream data = client.OpenRead(args[0]);
using StreamReader reader = new StreamReader(data);
string s = reader.ReadToEnd();
Console.WriteLine(s);
}
}
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
Using 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;)")
Using data As Stream = client.OpenRead(args(0))
Using reader As New StreamReader(data)
Dim s As String = reader.ReadToEnd()
Console.WriteLine(s)
End Using
End Using
End Using
End Sub
End Class
備註
謹慎
WebRequest、HttpWebRequest、ServicePoint和 WebClient 已經過時，您不應該將它們用於新的開發。 請改用 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 設定為 WebClient 實例中的 true。
給繼承者的注意事項
衍生類別應該呼叫 WebClient 的基類實作，以確保衍生類別如預期般運作。
建構函式
| WebClient() |
已淘汰.
初始化 WebClient 類別的新實例。 |
屬性
| AllowReadStreamBuffering |
已淘汰.
取得或設定值，這個值表示是否要緩衝從因特網資源讀取 WebClient 實例的數據。 |
| AllowWriteStreamBuffering |
已淘汰.
取得或設定值，這個值表示是否要緩衝寫入 WebClient 實例之因特網資源的數據。 |
| BaseAddress |
取得或設定 WebClient所提出要求的基底 URI。 |
| CachePolicy |
取得或設定此 WebClient 實例使用 WebRequest 物件取得之任何資源的應用程式快取原則。 |
| CanRaiseEvents |
取得值，指出元件是否可以引發事件。 (繼承來源 Component) |
| Container |
取得包含 Component的 IContainer。 (繼承來源 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 |
已淘汰.
發生於使用寫入數據流將數據寫入資源的異步操作關閉時。 |
