Using Windows PowerShell to Create BITS Transfer Jobs

Using Windows PowerShell to Create BITS Transfer Jobs

You can use PowerShell cmdlets to create synchronous and asynchronous Background Intelligent Transfer Service (BITS) transfer jobs.

All of the examples in this topic use the Start-BitsTransfer cmdlet. To use the cmdlet, be sure to import the module first. To install the module, run the following command: Import-Module BitsTransfer. For more information, type Get-Help Start-BitsTransfer at the PowerShell prompt.


When you use *-BitsTransfer cmdlets from within a process that runs in a noninteractive context, such as a Windows service, you may not be able to add files to BITS jobs, which can result in a suspended state. For the job to proceed, the identity that was used to create a transfer job must be logged on. For example, when creating a BITS job in a PowerShell script that was executed as a Task Scheduler job, the BITS transfer will never complete unless the Task Scheduler's task setting "Run only when user is logged on" is enabled.


To create a synchronous BITS transfer job

Start-BitsTransfer -Source http://Server01/serverdir/testfile1.txt `
-Destination C:\clientdir\testfile1.txt

Note  The grave-accent character (`) is used to indicate a line break.

In the preceding example, the local and remote names of the file are specified in the Source and Destination parameters, respectively. The command prompt returns when the file transfer is complete or when it enters an error state.

The default transfer type is Download. When you upload files to an HTTP location, the TransferType parameter must be set to Upload.

Because parameter position is enforced for the Start-BitsTransfer cmdlet, the parameter names do not need to be specified for the Source and Destination parameters. Therefore, this command can be simplified as follows.

Start-BitsTransfer http://Server01/serverdir/testfile1.txt C:\clientdir\testfile1.txt

To create a synchronous BITS transfer job with multiple files

Start-BitsTransfer -Source C:\clientsourcedir\*.txt `
-Destination c:\clientdir\ -TransferType Download

In the preceding example, the Start-BitsTransfer command creates a new BITS transfer job. All of the files are added to this job and transferred sequentially to the client.

Note  The destination path cannot use wildcard characters. The destination path supports relative directories, root paths, or implicit directories (that is, the current directory). Destination files cannot be renamed by using a wildcard character. Additionally, HTTP and HTTPS URLs do not work with wildcards. Wildcards are only valid for UNC paths and local directories.

To create a synchronous BITS transfer job and specify credentials for a remote server

Start-BitsTransfer -DisplayName MyJob -Credential Username\Domain `
-Source http://server01/servertestdir/testfile1.txt -Destination c:\clienttestdir\testfile1.txt `
-ProxyUsage Override -ProxyList @(http://proxy1,, proxy3)

In the preceding example, a user creates a BITS transfer job to download a file from a server that requires authentication. The user is prompted for credentials, and the Credential parameter passes a credential object to the Start-BitsTransfer cmdlet. The user sets an explicit proxy, and the BITS transfer job uses only the proxies that are defined by the ProxyList parameter. The DisplayName parameter gives the BITS transfer job a unique display name.

To create a synchronous BITS transfer job from a CSV file

Import-CSV filelist.txt | Start-BitsTransfer -TransferType Upload

Note  The "|" is the pipe character.

In the preceding example, a user creates a BITS transfer job that uploads multiple files from a client. The Import-CSV cmdlet imports the source and destination file locations and pipes them to the Start-BitsTransfer command. The Start-BitsTransfer command creates a new BITS transfer job for each file, adds the files to the job, and then transfers them sequentially to the server.

The contents of the Filelist.txt file should be in the following format:

Source, Destination
c:\clienttestdir\testfile1.txt, http://server01/servertestdir/testfile1.txt
c:\clienttestdir\testfile2.txt, http://server01/servertestdir/testfile2.txt
c:\clienttestdir\testfile3.txt, http://server01/servertestdir/testfile3.txt
c:\clienttestdir\testfile4.txt, http://server01/servertestdir/testfile4.txt

To create an asynchronous BITS transfer job

$Job = Start-BitsTransfer -Source `
       -Destination d:\temp\downloads\ -Asynchronous

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

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

In the preceding example, the BITS transfer job was assigned to the $Job variable. The files are downloaded sequentially. After the transfer job is complete, the files are immediately available. If $Job.JobState returns "Transferred", the $Job object is sent to the Complete-BitsTransfer cmdlet.

If $Job.JobState returns "Error", the $Job object is sent to the Format-List cmdlet to list the errors.

Related topics




© 2016 Microsoft