WebClient.DownloadFileAsync 方法

定義

命名空間:

System.Net

組件:

System.Net.WebClient.dll

以非同步作業的方式將指定資源下載至本機檔案。 這些方法不會封鎖呼叫執行緒。

多載

DownloadFileAsync(Uri, String)	將具有指定之 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫執行緒。
DownloadFileAsync(Uri, String, Object)	將具有指定之 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫執行緒。

DownloadFileAsync(Uri, String)

來源:

WebClient.cs

將具有指定之 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫執行緒。

public:
 void DownloadFileAsync(Uri ^ address, System::String ^ fileName);

public void DownloadFileAsync (Uri address, string fileName);

member this.DownloadFileAsync : Uri * string -> unit

Public Sub DownloadFileAsync (address As Uri, fileName As String)

參數

address

Uri

要下載之資源的 URI。

fileName

String

要置於本機電腦之檔案的名稱。

例外狀況

ArgumentNullException

address 參數為 null。

-或-

fileName 參數為 null。

WebException

合併 BaseAddress 和 address 而形成的 URI 是無效的。

-或-

下載資源時發生錯誤。

InvalidOperationException

fileName 指定的本機檔案正由其他執行緒使用。

備註

這個方法會在 參數中指定的 address URI 上下載資源。 下載成功完成時，下載的檔案會在本機計算機上命名 fileName 。 檔案會使用從線程集區自動配置的線程資源，以異步方式下載。 若要在檔案可用時接收通知，請將事件處理程式新增至 DownloadFileCompleted 事件。

此方法不會在下載資源時封鎖呼叫線程。 若要在等候下載完成時封鎖，請使用其中 DownloadFile 一種方法。

在 .NET Framework 和 .NET Core 1.0 中，您可以藉由呼叫 方法來取消尚未完成的CancelAsync異步操作。

BaseAddress如果屬性不是空字串 (“”“) 且address未指定絕對 URI，address則必須是結合BaseAddress的相對 URI，才能形成所要求數據的絕對 URI。 QueryString如果屬性不是空字串，則會附加至 address。

此方法會使用 RETR 命令來下載 FTP 資源。 針對 HTTP 資源，會使用 GET 方法。

注意

在應用程式中啟用網路追蹤時，這個成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

在 ASP.NET 頁面中使用這個方法時，如果頁面執行的帳戶沒有存取本機檔案的許可權，您會收到錯誤。

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException，仍會同步擲回。 如需預存的例外狀況，請參閱 所 DownloadFile(Uri, String)擲回的例外狀況。

DownloadFileAsync(Uri, String, Object)

來源:

WebClient.cs

將具有指定之 URI 的資源下載至本機檔案。 這個方法不會封鎖呼叫執行緒。

public:
 void DownloadFileAsync(Uri ^ address, System::String ^ fileName, System::Object ^ userToken);

public void DownloadFileAsync (Uri address, string fileName, object? userToken);

member this.DownloadFileAsync : Uri * string * obj -> unit

Public Sub DownloadFileAsync (address As Uri, fileName As String, userToken As Object)

參數

address

Uri

要下載之資源的 URI。

fileName

String

要置於本機電腦之檔案的名稱。

userToken

Object

使用者定義的物件，這個物件會在非同步作業完成時傳遞至叫用的方法。

例外狀況

ArgumentNullException

address 參數為 null。

-或-

fileName 參數為 null。

WebException

合併 BaseAddress 和 address 而形成的 URI 是無效的。

-或-

下載資源時發生錯誤。

InvalidOperationException

fileName 指定的本機檔案正由其他執行緒使用。

備註

這個方法會在 參數中指定的 address URI 上下載資源。 下載成功完成時，下載的檔案會在本機計算機上命名 fileName 。 檔案會使用從線程集區自動配置的線程資源，以異步方式下載。 若要在檔案可用時接收通知，請將事件處理程式新增至 DownloadFileCompleted 事件。

此方法不會在下載資源時封鎖呼叫線程。 若要在等候下載完成時封鎖，請使用其中 DownloadFile 一種方法。

在 .NET Framework 和 .NET Core 1.0 中，您可以藉由呼叫 方法來取消尚未完成的CancelAsync異步操作。

BaseAddress如果屬性不是空字串 (“”“) 且address未指定絕對 URI，address則必須是結合BaseAddress的相對 URI，才能形成所要求數據的絕對 URI。 QueryString如果屬性不是空字串，則會附加至 address。

此方法會使用 RETR 命令來下載 FTP 資源。 針對 HTTP 資源，會使用 GET 方法。

注意

在應用程式中啟用網路追蹤時，這個成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

在 ASP.NET 頁面中使用這個方法時，如果頁面執行的帳戶沒有存取本機檔案的許可權，您會收到錯誤。