Introducing BITS PowerShell Cmdlets!

UPDATE: BITS PowerShell cmdlets has gone through some changes between Win7 beta and Win7 RC. This posting has been updated accordingly.

---- 

The BITS (Background Intelligent Transfer Service) team is happy to announce the release of BITS PowerShell cmdlets in Windows 7! BITS PowerShell cmdlets combine the richness and usability of PowerShell scripting with the network-awareness and persistence of BITS file transfers. We believe that the addition of BITS cmdlets will make it easier for admins to manage and automate file transfer tasks by providing the following benefits.

For PowerShell admins considering BITS:

· Politeness: File transfers can be conducted in the background to preserve the responsiveness of other network apps

· Fire-and-forget persistence: BITS automatically tries to resume transfers that have been interrupted by temporary hiccups such as network disconnections or system reboots

For BITS API and BITSAdmin considering the switch to PowerShell cmdlets:

· Admin-Focused: Automate file transfers tasks in an extensible and management-oriented scripting language

· Usability: Consistent syntax across PowerShell cmdlets makes PowerShell scripting easy to learn and use

A primer on BITS can be found at https://msdn.microsoft.com/en-us/library/aa362708(VS.85).aspx.

On your mark…

Before using the BITS cmdlets, they must be loaded using the following cmdlet.

Import-Module FileTransfer Import-Module BitsTransfer

This cmdlet needs to be called whenever a new PowerShell session is started. This step can be avoided by adding the above cmdlet to your profile script. The location of this script is given by the $profile variable. Once this has been added to the profile script, the BITS cmdlets are loaded whenever a new PowerShell session is started.

Get set…

Discovering and navigating through all of the BITS PowerShell cmdlets can be a daunting task. A good place to start is by running the following cmdlet, which lists all of the BITS PowerShell cmdlets.

Get-Command –Module FileTransfer Get-Command -Module BitsTransfer

 

 

Without further ado, here are the BITS cmdlets in a nutshell… or PowerShell.

Start Your Engines

New-FileTransfer Start-BitsTransfer

Creates a BITS job to transfer one or more files between two locations. By default, this cmdlet operates in synchronous mode and returns when all files have been transferred. A file transfer done in this mode is similar to a simple copy command. Managing file transfer tasks is not supported in this mode since it blocks until all files have been transferred.

This cmdlet can also operate in asynchronous mode, where it returns a BITS job object immediately. Think of this mode as the starting point for managing file transfers tasks. In general, a BITS job should be created asynchronously before passing it as a parameter to the other BITS cmdlets .

(Note: It is possible to modify synchronously created BITS jobs from a different PowerShell session using BITS cmdlets or from a CMD prompt using the BITSAdmin tool. This is not recommended, since it is much simpler to just modify BITS jobs created using the asynchronous mode.)

Meet Your Pit Crew

Add-FileTransfer Add-BitsFile

Adds one or more files to a BITS job.

Get-FileTransfer Get-BitsTransfer

Retrieves a list of BITS jobs for the current user. This cmdlet is handy for piping a list of BITS jobs into another cmdlet. For example, you can pipe this into the Remove-BitsTransfer cmdlet to cancel all BITS jobs.

Set-FileTransfer Set-BitsTransfer

Modifies the properties of a BITS job. This is handy for changing BITS job properties on the fly, such as changing the aggressiveness of a BITS job.

Suspend-FileTransfer Suspend-BitsTransfer

Suspends a BITS job. This cmdlet pauses a BITS job’s file transfers until the BITS job is resumed by the Resume-BitsTransfer cmdlet.

Resume-FileTransfer Resume-BitsTransfer

Resumes a BITS job. Calling this cmdlet will resume a suspended BITS job and start file transfers from where they left off.

Complete-FileTransfer Complete-BitsTransfer

Completes and removes a BITS job. Using this cmdlet will save any transferred files and remove the BITS job.

Clear-FileTransfer Remove-BitsTransfer

Cancels and removes a BITS job. This is similar to Complete-BitsTransfer with one exception. Files that are part of the BITS job will not be saved, even if they have been transferred.

Go!!

Give the BITS cmdlets a test drive and explore how they can be used to satisfy your file transfer needs. Keep reading in the future for some examples and ideas on using BITS cmdlets!

Lost, Need Directions?

For examples and documentation on how to use each cmdlet, try looking at the cmdlet help.

Get-Help <Cmdlet Name>

For more information about BITS, check out the following link:

https://msdn.microsoft.com/en-us/library/bb968799(VS.85).aspx

 

 

Alex Ng [MSFT]

Comments

• Anonymous
  January 22, 2009
  PingBack from http://blog.a-foton.ru/index.php/2009/01/23/introducing-bits-powershell-cmdlets/

• Anonymous
  January 23, 2009
  I was in a meeting yesterday talking about BITS and what an awesome service it was.&#160; I described

• Anonymous
  February 04, 2009
  Is there a way to subscribe to an event related to the BITS job so I can launch an async transfer and then automatically complete it when it's finished? I see there's event support in the BITS api but I'm not finding it in the Powershell BITS job object.

• Anonymous
  February 04, 2009
  @Paul Unfortunately, there is no completion callback support in BITS PS objects. If you want the job to automatically complete when finished there are two ways:

1. You can either use a synchronous transfer or,
2. You can continuously poll the JobState field of the BITS job object until it has entered "Transferred" state and then complete the job.

• Anonymous
  February 04, 2009
  Thanks for the fast response. That method will work fine, these cmdlets are too cool!

• Anonymous
  March 22, 2009
  Je viens de le voir dans un post sur le blog du team PowerShell , et un autre sur le blog WMI : PowerShell

• Anonymous
  April 06, 2009
  The people over on WMI, WinRM, and BITS have started up a blog to share their systems management expertise

• Anonymous
  April 07, 2009
  The people over on WMI, WinRM, and BITS have started up a blog to share their systems management expertise

• Anonymous
  April 09, 2009
  Feed: Windows PowerShell Blog Posted on: Monday, April 06, 2009 4:35 PM Author: PowerShellTeam Subject

• Anonymous
  May 29, 2009
  Does not work for me (Win 7 RC): PS B:Windowssystem32> Import-Module FileTransfer Import-Module : The specified module 'FileTransfer' was not loaded because no valid module file was found in any module directory. Bei Zeile:1 Zeichen:14

• Import-Module <<<<  FileTransfer    + CategoryInfo          : ResourceUnavailable: (FileTransfer:String) [Import-Module], FileNotFoundException    + FullyQualifiedErrorId : Modules_ModuleNotFound,Microsoft.PowerShell.Commands.ImportModuleCommand

• Anonymous
  June 15, 2009
  If you have been using BITS PowerShell cmdlets since the Windows 7 beta and are currently running the

• Anonymous
  June 29, 2009
  Thanks to Register-ObjectEvent We can complete the job automatically when it finished.

• Anonymous
  July 31, 2009
  Is it possible to manage the BITS client service from WSH ? Any WMI interface ?

• Anonymous
  August 12, 2009
  The comment has been removed

• Anonymous
  May 26, 2010
  Unfortunately there seems to be an 'undocumented feature' (?bug?) in start-bitstransfer powershell cmmdlet that prevents it working when scheduled inside a task with the user logged off. I have spent 5 days on this and the evidence is conclusive. All info is here: powershellcommunity.org/.../Default.aspx and www.blakes.net/.../Post.aspx I'd love somone to prove me wrong - but no-one has....alternatively can someone from the design time confirm that this is an 'oversight' and I should stop wasting my time :(

• Anonymous
  November 20, 2014
  What is the difference between Start-BitsTransfer and copy-item?