PowerShell Logo Small

Start-BitsTransfer



This is the built-in help made by Microsoft for the command 'Start-BitsTransfer', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates a new Background Intelligent Transfer Service (BITS) transfer job.

SYNTAX


Start-BitsTransfer [-Source] <String[]> [[-Destination] <String[]>] [-Asynchronous] [-Authentication <String>] [-Credential <PSCredential>] [-Description <String>]
[-DisplayName <String>] [-Priority <String>] [-ProxyAuthentication <String>] [-ProxyBypass <String[]>] [-ProxyCredential <PSCredential>] [-ProxyList <Uri[]>] [-ProxyUsage
<String>] [-RetryInterval <Int32>] [-RetryTimeout <Int32>] [-Suspended] [-TransferPolicy {Always | BelowCap | Capped | IgnoreCongestion | NearCap | None | NoSurcharge |
NotRoaming | OverCapCharged | OverCapThrottled | PolicyUnrestricted | Roaming | Standard | Unrestricted | UsageBased}] [-TransferType <String>] [-UseStoredCredential {None |
Proxy | Server}] [-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The Start-BitsTransfer cmdlet creates a new BITS transfer job to transfer one or more files between a client computer and a server. The TransferType parameter specifies the
direction of the transfer. By default, after the cmdlet begins the transfer, the command prompt is not available until the transfer is complete or until the transfer enters
an error state. If the state of the returned BitsJob object is Error, the error code and description are contained in the object and can be used for analysis.


The Start-BitsTransfer cmdlet supports downloading multiple files from a server to a client computer, but it does not generally support uploading multiple files from a
client computer to a server. If you need to upload more than one file, you can use the Import-CSV cmdlet to pipe the output to the Add-BitsFile cmdlet to upload multiple
files. Or, if you need to upload more than one file, consider using a cabinet file (.cab) or a compressed file (.zip).



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=287263
Add-BitsFile
Complete-BitsTransfer
Get-BitsTransfer
Remove-BitsTransfer
Resume-BitsTransfer
Set-BitsTransfer
Suspend-BitsTransfer

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

C:\PS>Start-BitsTransfer -Source http://server01/servertestdir/testfile1.txt -Destination c:\clienttestdir\testfile1.txt



This command creates a new BITS transfer job that downloads a file from a server. The local and remote names of the file are specified in the Source and Destination
parameters. Because the default transfer type is Download, the http://Server01/servertestdir/testfile1.txt file is transferred to C:\clienttestdir\testfile1.txt on the
client. The command prompt returns when the file transfer is complete or when it enters an error state.

When you upload files to an HTTP location, the TransferType parameter must be set to Upload.

Because the Start-BitsTransfer cmdlet assumes that the first parameter is the source and that the second parameter is the destination when no value is specified, this
command could be simplified as follows:

Start-BitsTransfer http://server01/servertestdir/testfile1.txt c:\clienttestdir\testfile1.txt




-------------------------- EXAMPLE 2 --------------------------

C:\PS>Import-CSV filelist.txt | Start-BitsTransfer



This command creates BITS transfer jobs that download multiple files from a server.

The command imports the source and destination file locations and then pipes the locations to the Start-BitsTransfer command. The Start-BitsTransfer command creates a new
BITS transfer job for each of the files in filelist.txt and then transfers them concurrently to the client.

The contents of the filelist.txt file resemble the following information:

Source, Destination

http://server01/servertestdir/testfile1.txt, c:\clienttestdir\testfile1.txt

http://server01/servertestdir/testfile2.txt, c:\clienttestdir\testfile2.txt

http://server01/servertestdir/testfile3.txt, c:\clienttestdir\testfile3.txt

http://server01/servertestdir/testfile4.txt, c:\clienttestdir\testfile4.txt




-------------------------- EXAMPLE 3 --------------------------

C:\PS>Start-BitsTransfer -Source c:\clienttestdir\testfile1.txt -Destination http://server01/servertestdir/testfile1.txt -TransferType Upload



This command creates a new BITS transfer job that uploads a file to a server. The local and remote names of the file are specified in the Source and Destination parameters.
Because the default transfer type is Download, the TransferType parameter must be set to Upload. The C:\clienttestdir\testfile1.txt file on the client is transferred to
http://Server01/servertestdir/testfile1.txt. The command prompt returns when the file transfer is complete or enters an error state.

Important: The Start-BitsTransfer cmdlet lets you download multiple files from a server to a client computer, but it does not typically let you upload multiple files from a
client computer to a server. It is possible to work around this limitation by using the Import-CSV cmdlet to pipe the output to the Start-BitsTransfer cmdlet. If you need to
upload more than one file, you can also use a .cab or .zip file.

Because the Start-BitsTransfer cmdlet assumes that the first parameter is the source and that the second parameter is the destination when no value is specified, this
command could be simplified as follows:

Start-BitsTransfer c:\clienttestdir\testfile1.txt http://server01/servertestdir/testfile1.txt -TransferType Upload




-------------------------- EXAMPLE 4 --------------------------

C:\PS>Start-BitsTransfer -Source http://server01/servertestdir/testfile1.txt, http://server01/servertestdir/testfile1.txt -Destination c:\clienttestdir\testfile1.txt,
c:\clienttestdir\testfile1.txt



This command creates a new BITS transfer job that downloads multiple files from a server.

The local and remote names of the files are specified in the Source and Destination parameters. Because the default of the TransferType parameter is Download, the
http://Server01/servertestdir/testfile1.txt and http://Server01/servertestdir/testfile2.txt files are transferred to C:\clienttestdir\testfile1.txt and
C:\clienttestdir\testfile2.txt on the client computer. The command prompt returns when the file transfer is complete or enters an error state.




-------------------------- EXAMPLE 5 --------------------------

C:\PS>$c = Get-CredentialPS C:\>Start-BitsTransfer -DisplayName MyJob -Credential $c -Source http://server01/servertestdir/testfile1.txt -Destination
c:\clienttestdir\testfile1.txt



These commands create a new BITS transfer job that downloads a file from a server by using a specific set of credentials.

The first command retrieves a set of credentials from the user by calling the Get-Credential cmdlet. The returned PSCredential object is stored in the $c variable.

The second command uses the Credential parameter to pass the PSCredential object that is stored in the $c variable to the Start-BitsTransfer cmdlet. A new BITS transfer job
is created that downloads the http://server01/servertestdir/testfile1.txt file to the client. The specified credentials are used to authenticate the user at the server.
Additionally, the optional DisplayName parameter is used to give the BITS transfer job a unique name.




-------------------------- EXAMPLE 6 --------------------------

C:\PS>Import-CSV filelist.txt | Start-BitsTransfer -Asynchronous -Priority Normal



This command creates BITS transfer jobs that download multiple files from a server. The files will be downloaded sequentially, but they will be available immediately when
the transfer job is complete.

The command imports the source and destination file locations and then pipes them to the Start-BitsTransfer command. The Start-BitsTransfer command creates a new BITS
transfer job for each of the files in filelist.txt and then transfers them sequentially to the client.

The contents of the filelist.txt file resemble the following information:

Source, Destination

http://server01/servertestdir/testfile1.txt, c:\clienttestdir\testfile1.txt

http://server01/servertestdir/testfile2.txt, c:\clienttestdir\testfile2.txt

http://server01/servertestdir/testfile3.txt, c:\clienttestdir\testfile3.txt

http://server01/servertestdir/testfile4.txt, c:\clienttestdir\testfile4.txt




-------------------------- EXAMPLE 7 --------------------------

C:\PS>Start-BitsTransfer -Source http://server01/servertestdir/*.* -Destination c:\clienttestdir\



This command creates a new BITS transfer job that downloads multiple files from a server.

The Start-BitsTransfer command creates a new BITS transfer job. All the files are added to a single job and then transferred sequentially to the client.

The following command shows another variation of a file transfer command that uses a wildcard character:

Start-BitsTransfer -Source http://server01/servertestdir/*.txt -Destination c:\clienttestdir\

The destination path cannot use wildcard characters. The destination path supports only a relative directory, a rooted path, or an implicit directory (the current
directory). Additionally, the destination files cannot be renamed by using a wildcard character. For example, the following command does not work:

c:\clienttestdir\*.BAK




-------------------------- EXAMPLE 8 --------------------------

C:\PS>Import-CSV filelist.txt | Start-BitsTransfer -TransferType Upload



This command creates BITS transfer jobs that upload multiple files to a server.

The command imports the source and destination file locations and then pipes them to the Start-BitsTransfer command. The Start-BitsTransfer command creates a new BITS
transfer job for each of the files in filelist.txt and then transfers them concurrently to the server.

The contents of the filelist.txt file resemble the following information:

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




-------------------------- EXAMPLE 9 --------------------------

PS C:\>Start-BitsTransfer -Source .\Patch0416.msu -Destination $env:temp\Patch0416.msu -ProxyUsage Override -ProxyList BitsProxy:8080 -ProxyCredential Server01\Admin01



This command uses the Start-BitsTransfer cmdlet to copy a patch file from a server on one network to a client on a different network when the networks are connected only by
a proxy server.

This scenario arises when an Internet-connected server downloads files and then distributes them to computers on disconnected or isolated networks that have no Internet
access.

BITS can detect proxy server settings automatically. However, if the proxy servers are not configured for automatic detection, you can override the automatic detection
mechanism and identify the proxy server explicitly, as shown in this example.

The command uses the Source parameter to specify the location of the patch on the server computer and the Destination parameter to specify the intended location of patch on
the client computer. It uses the ProxyUsage parameter with a value of Override to override the automatic proxy server detection mechanism. To identify the proxy server, it
uses the ProxyList parameter. The value of the ProxyList parameter is a URI with a <Name:Port> format. Finally, it uses the ProxyCredential parameter to specify the
credentials of an administrator who has permission to connect to the proxy server.