dotnet / dotnet/winforms

Add Async versions of DownloadFile

Open
#11,747 3 comments 0 reactions 1 assignee Claimed by @KlausLoeffelmann View on GitHub
api-suggestion
Dominant language
C#
Stars
4.9k
Forks
1.1k
Avg merge
20h 23m
Merged PRs (30d)
103

Description

### Background and motivation

In order to update Microsoft.VisualBasic.Devices.Network to use HttpClient a set of DownloadFileAsyc needed to be create but they are now Friend Shared. It would be useful if the Async versions were available to developers, and they are already written and tested.

### API Proposal

It is possible to match all the current Microsoft.VisualBasic.Devices.Network.DownloadFile API but the set below is also reasonable. It is also possible to have many few using optional parameters. Some below are currently commented out as unnecessary for replacement of WebClient.

```vb
'''
''' Sends and receives a packet to and from the passed in Uri.
''' Maps older networkCredentials to HttpClientHandler.
'''
''' Uri to the remote file.
''' Name and path of file where download is saved.
''' The credentials of the user performing the download.
''' A ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
'''
Friend Shared Function DownloadFileAsync(
addressUri As Uri,
destinationFileName As String,
networkCredentials As ICredentials,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean,
onUserCancel As UICancelOption) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Uri to the remote file
''' Name and path of file where download is saved.
''' The name of the user performing the download.
''' The user's password.
''' A ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
Friend Shared Async Function DownloadFileAsync(
addressUri As Uri,
destinationFileName As String,
userName As String,
password As String,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Uri to the remote file
''' Name and path of file where download is saved.
''' The name of the user performing the download.
''' The user's password.
''' ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
''' Indicates what to do if user cancels dialog (either throw or do nothing).
Friend Shared Async Function DownloadFileAsync(
addressUri As Uri,
destinationFileName As String,
userName As String,
password As String,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean,
onUserCancel As UICancelOption) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Uri to the remote file
''' Name and path of file where download is saved.
''' An HttpClientHandler of the user performing the download.
''' Progress Dialog.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
''' Indicates what to do if user cancels dialog (either throw or do nothing).
''' Calls to all the other overloads will come through here.
Friend Shared Async Function DownloadFileAsync(
addressUri As Uri,
destinationFileName As String,
clientHandler As HttpClientHandler,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean,
onUserCancel As UICancelOption) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Address to the remote file, http, ftp etc...
''' Name and path of file where download is saved.
''' The name of the user performing the download.
''' The user's password.
''' A ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
Friend Shared Async Function DownloadFileAsync(
address As String,
destinationFileName As String,
userName As String,
password As String,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Address to the remote file, http, ftp etc...
''' Name and path of file where download is saved.
''' The name of the user performing the download.
''' The user's password.
''' A ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
''' Indicates what to do if user cancels dialog (either throw or do nothing).
Friend Shared Async Function DownloadFileAsync(
address As String,
destinationFileName As String,
userName As String,
password As String,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean,
onUserCancel As UICancelOption) As Task

'''
''' Downloads a file from the network to the specified path.
'''
''' Uri to the remote file
''' Name and path of file where download is saved.
''' The credentials of the user performing the download.
''' A ProgressDialog or Nothing.
''' Time allotted before giving up on a connection.
''' Indicates whether or not the file should be overwritten if local file already exists.
'''
''' Function will Throw on unhandled exceptions.
'''
Friend Shared Async Function DownloadFileAsync(
addressUri As Uri,
destinationFileName As String,
networkCredentials As ICredentials,
dialog As ProgressDialog,
connectionTimeout As Integer,
overwrite As Boolean) As Task
```

### API Usage

```VB
Dim t As Task = DownloadFileAsync(
addressUri:=address,
destinationFileName,
networkCredentials,
dialog,
connectionTimeout,
overwrite,
onUserCancel)

```

### Alternative Designs

Just a few Async API's with many optional parameters or exactly copy DownloadFile API's and make them all Async

### Risks

There is already 100% test coverage in FixIssue#9807 PR so risk is minimal.

### Will this feature affect UI controls?

No

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.