Add Async versions of DownloadFile
- 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
Assessment
This issue has not been assessed yet.