For this Tip of the Week, we are going to cover some more of the BITS PowerShell cmdlets. Two weeks ago, we covered Start-BitsTransfer and talked about a couple of quick scenarios on how to use the cmdlet. Now, we will explore the other cmdlets to see how they can be used in conjunction with the Start-BitsTransfer cmdlet.
EXAMPLE SCENARIO
Example 1
For this scenario we have a large file transfer that is occurring, one that was kicked off with Start-BitsTransfer. It is a large transfer as well. Because the file being ‘transferred’ is large, we can use the Get-BitsTransfer cmdlet to review it’s progress:
[sourcecode language=”powershell”]
Get-BitsTransfer
[/sourcecode]
[sourcecode language=”powershell”]
Get-BitsTransfer | Fl
[/sourcecode]
Now, remember that the transfer is occurring in the other PowerShell Window. When we suspend the transfer, we can seee the suspension in both Windows:
(Initiated Shell)
(Shell where the transfer was suspended)
** NOTE ** If managing a large amount of Bits Transfers is necessary, it might be a good practice to provide a good Display Name to help differentiate between each transfer being managed. The file or files being downloaded are not listed when running the Get-BitsTransfer cmdlet.
From here we can decided to Resume the Bits Transfer or remove the Bits Transfer as well. Once suspended, we can deterine the next action for the Bits Transfer, like Resume, Complete and Remove. If we decide the fileis no longer needed, we can use the Remove-BitsTransfer cmdlet like so:
[sourcecode language=”powershell”]
$BitsJob = Get-BitsTransfer -Name 'Bits Transfer'
Remove-BitsTransfer -BitsJob $BitsJob
[/sourcecode]
Which shows no feedback when run:
If we want to cancel all jobs, we can run this:
[sourcecode language=”powershell”]
Get-BitsTransfer | Remove-BitsTransfer
[/sourcecode]
If we want to either Resume or Complete the transfer, we can do this:
[sourcecode language=”powershell”]
$BitsJob = Get-BitsTransfer -Name 'Bits Transfer'
Resume-BitsTransfer -BitsJob $BitsJob
[/sourcecode]
OR
[sourcecode language=”powershell”]
$BitsJob = Get-BitsTransfer -Name 'Bits Transfer'
Complete-BitsTransfer -BitsJob $BitsJob
[/sourcecode]
Then the job will run to completion and your files can be accessed.
Additional Options
When creating a job, we have other options:
Asynchronous: Runs the job in the background and the PowerShell command prompt is available again.
Authentication: Specify an authentication type for the Source [Basic, Digest, NTLM, Negotiate or Passport]
Credential: Used to authenticate to a source that requires credentials
Description: Helpful information for us to determine what the job is for.
DisplayName: A name we can use to visually distinguish between jobs.
Proxy Parameters: Allows us to use a Proxy to download files in case one is in place.
ProxyAuthentication, ProxyBypass, ProxyCredential, ProxyList and ProxyUsage
RetryInterval: When a job is retried if a connection is not made. Minimum value is 60 seconds, default is 600
RetryTimeout: If the job is not completed in this time, then job will fail. Default is 14 days.
TransferPolicy: Used if there needs to be a cost assigned to the download due to congestion, data caps, etc.
Accepted Values: None, Unrestricted, Capped, BelowCap, NearCap, OverCapCharged, OverCapThrottled, UsageBased, Roaming, IgnoreCongestion, PolicyUnrestricted, Standard, NoSurcharge, NotRoaming, Always
TransferType: Specify the type of download whether it is a download, upload or a uploadreply:
Download (the default): File is being downloaded
Upload: Job is uploading a file to a server
UploadReply: Job will upload a file and download a reply file
UseStoredCredential: Only use this if Proxy Credentials are needed, and then specify Proxy as the value for this parameter. If Proxy is used, then the ProxyCredential parameter must also be used.
CONCLUSION
As we can see, the Bits Transfer cmdlets provide some interesting capabilities. As a script author, I have used this script for downloading files needed to perform certain tasks. These tasks range from a Prerequisite installer script, to a health script to a script that downloaded needed files or moved needed files to a desired location. Bits Transfer makes this easy to manage and handle multiple source and destination targets.
FURTHER READING
I cover this and many more topics in this book:
Notes from the Field: A PowerShell Primer
|
