PowerShell How-To

Leverage BITS for File Transfers with PowerShell

Background Intelligent Transfer Service is a useful tool for transferring large files or transferring to a system with connectivity issues.

Performing simple file copies with PowerShell is fairly straightforward. Copy-Item will copy suffice when copying single files or whole folders of stuff. A problem arises, though, when the network you're transferring files across is flaky, the machine you're copying to doesn't maintain the connection it's supposed to or a number of other connectivity problems arise. Also, perhaps you're transferring some huge files across the wire that drastically affects overall network performance. Copy-Item has no way to account for any of these scenarios. In these situations, transferring files using BITS should be looked into.

Background Intelligent Transfer Service (BITS) has been around for a long time and is heavily used by Microsoft most popularly to deliver updates to all Windows computers through the Windows Update service. BITS is smart. BITS has native controls built-in to account for lots of different problems that may arise when transferring files.

BITS is leveraged in PowerShell through the BitsTransfer cmdlets.

PS> Get-Command -Noun BitsTransfer

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Cmdlet          Complete-BitsTransfer                              2.0.0.0    BitsTransfer
Cmdlet          Get-BitsTransfer                                   2.0.0.0    BitsTransfer
Cmdlet          Remove-BitsTransfer                                2.0.0.0    BitsTransfer
Cmdlet          Resume-BitsTransfer                                2.0.0.0    BitsTransfer
Cmdlet          Set-BitsTransfer                                   2.0.0.0    BitsTransfer
Cmdlet          Start-BitsTransfer                                 2.0.0.0    BitsTransfer
Cmdlet          Suspend-BitsTransfer                               2.0.0.0    BitsTransfer

The BITS cmdlets allow you to start, manage, suspend and remove BITS jobs. BITS transfer, unlike Copy-Item transfer, are done with jobs. This means that background jobs can be leveraged when performing large file copies which means much faster overall transfers!

Copying Files
To get started using the BITS cmdlets, let's just copy a single file. To start any BITS job, we need to use Start-BitsTransfer. When using BITS cmdlets like this, it's very similar to the syntax when using Copy-Item.

 

Start-BitsTransfer -Source C:\file.txt -Destination \\server\c$

Using the Source and Destination parameters is just the beginning of working with the Start-BitsTransfer cmdlet. Check out all of the other options we, by no means, have time for in this article.

 

S> help start-bitstransfer

NAME
Start-BitsTransfer

SYNOPSIS
Creates a BITS transfer job.


SYNTAX
Start-BitsTransfer [-Source] <String[]> [[-Destination] <String[]>] [-Asynchronous] [-Authentication {Basic | Digest | Ntlm | Negotiate | Passport}] [-Credential <PSCredential>]
[-Description <String>] [-DisplayName <String>] [-Priority {Foreground | High | Normal | Low}] [-ProxyAuthentication {Basic | Digest | Ntlm | Negotiate | Passport}] [-ProxyBypass
<String[]>] [-ProxyCredential <PSCredential>] [-ProxyList <Uri[]>] [-ProxyUsage {SystemDefault | NoProxy | AutoDetect | Override}] [-RetryInterval <Int32>] [-RetryTimeout <Int32>]
[-Suspended] [-TransferPolicy {Always | BelowCap | Capped | IgnoreCongestion | NearCap | None | NoSurcharge | NotRoaming | OverCapCharged | OverCapThrottled | PolicyUnrestricted |
Roaming | Standard | Unrestricted | UsageBased}] [-TransferType {Download | Upload | UploadReply}] [-UseStoredCredential {None | Proxy | Server}] [-Confirm] [-WhatIf]
[<CommonParameters>]

Using a Credential
Another great thing about using BITS over Copy-Item is the ability to use alternate credentials to perform the copy. If needing to copy files to a destination where the currently logged in user does not have access, we can simply use the Credential parameter to authenticate to the destination computer and begin the transfer.

Start-BitsTransfer -Source C:\file.txt -Destination \\server\c$  -Credential (Get-Credential)

Asynchronous Jobs
Perhaps you've got a huge set of files that need moved and need to initiate the transfer but continue on with the rest of your script. Since BITS always creates jobs under the covers, the Asynchronous parameter can be used to immediatelyreturn control back to the script upon execution. When the Asynchronous parameter is used, Start-BitsTransfer automatically returns a background job which can then be monitored. Below is an example:

$Job = Start-BitsTransfer -Source http://WebServer/HugeFile.zip  -Destination C:\Folder -Asynchronous

while (($Job.JobState -eq "Transferring") -or ($Job.JobState -eq "Connecting")) `
{ sleep 5;} # Poll for status, sleep for 5 seconds, or perform an action.

Switch($Job.JobState)
{
"Transferred" {Complete-BitsTransfer -BitsJob $Job}
"Error" {$Job | Format-List } # List the errors.
default {"Other action"} #  Perform corrective action.
}

Above we're starting a transfer, waiting for it to finish and then once complete, completing the transfer. This type of logic can be inserted anywhere in the script. It doesn't necessarily have to be right after the transfer is started.

There are a lot more things that are possible using the BITS cmdlets in PowerShell. These types of cmdlets are a great source of opportunity for developing bigger tools to create your own, robust file transfer module!

About the Author

Adam Bertram is an independent consultant, technical writer, trainer and presenter. Adam specializes in consulting and evangelizing all things IT automation mainly focused around Windows PowerShell. Adam is a Microsoft Windows PowerShell MVP, 2015 powershell.org PowerShell hero and has numerous Microsoft IT pro certifications. He is a writer, trainer and presenter and authors IT pro course content for Pluralsight. He is also a regular contributor to numerous print and online publications and presents at various user groups and conferences. You can find Adam at adamtheautomator.com or on Twitter at @adbertram.

comments powered by Disqus

SharePoint Watch

Sign up for our newsletter.

I agree to this site's Privacy Policy.