powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Start-BitsTransfer



NAME
Start-BitsTransfer

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

SYNTAX
Start-BitsTransfer [-Source] [[-Destination] ] [-Asynchronous] [-Authentication ] [-Cr
edential ] [-Description ] [-DisplayName ] [-Priority ] [-ProxyAuthentication
] [-ProxyBypass ] [-ProxyCredential ] [-ProxyList ] [-ProxyUsage ]
[-RetryInterval ] [-RetryTimeout ] [-Suspended] [-TransferType ] [-Confirm] [-WhatIf] [ ameters>]


DESCRIPTION
The Start-BitsTransfer cmdlet creates a new BITS transfer job to transfer one or more files between a client comput
er and a server. The TransferType parameter specifies the direction of the transfer. By default, after the cmdlet b
egins 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 n
ot generally support uploading multiple files from a client computer to a server. If you need to upload more than o
ne 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).


PARAMETERS
-Asynchronous []
Allows the BITS transfer job to be created and then processed in the background. The command prompt reappears i
mmediately after the BITS transfer job is created. The returned BitsJob object can be used to monitor status an
d progress.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? true

-Authentication
Specifies the authentication mechanism to be used at the server. Possible values are:

- Basic: Basic is a scheme in which the user name and password are sent in clear text to the server or proxy.
- Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
- NTLM: NTLM is a challenge-response scheme that uses the credentials of the user for authentication in a Windo
ws-based network environment.
- Negotiate (the default): Negotiate is a challenge-response scheme that negotiates with the server or proxy to
determine which scheme to use for authentication. For example, this parameter value allows negotiation to dete
rmine whether the Kerberos protocol or NTLM is used.
- Passport: Passport is a centralized authentication service provided by Microsoft that offers a single logon f
or member sites.

Required? false
Position? named
Default value Negotiate
Accept pipeline input? false
Accept wildcard characters? false

-Credential
Specifies the credentials to use to authenticate the user at the server. The default is the current user. Type
a user name, such as "User01", "Domain01\User01", or "User@Contoso.com". Or, use the Get-Credential cmdlet to c
reate the value for this parameter. When you type a user name, you will be prompted for a password.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Description
Describes the BITS transfer job. The description is limited to 1,024 characters.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Destination
Specifies the destination location and the names of the files that you want to transfer. The destination names
are paired with the corresponding source file names. For example, the first file name specified in the Source p
arameter corresponds to the first file name in the Destination parameter, and the second file name in the Sourc
e parameter corresponds to the second file name in the Destination parameter. The Source and Destination parame
ters must have the same number of elements; otherwise, the command produces an error.

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-DisplayName
Specifies a display name for the BITS transfer job. The display name provides a user-friendly way to differenti
ate BITS transfer jobs.

Required? false
Position? named
Default value BitsJob
Accept pipeline input? false
Accept wildcard characters? false

-Priority
Sets the priority of the BITS transfer job, which affects bandwidth usage. You can specify the following values
:

- Foreground (default): Transfers the job in the foreground. Foreground transfers compete for network bandwidth
with other applications, which can impede the user's overall network experience. However, if the Start-BitsTra
nsfer command is being used interactively, this is likely the best option. This is the highest priority level.
- High: Transfers the job in the background with a high priority. Background transfers use the idle network ban
dwidth of the client computer to transfer files.
- Normal: Transfers the job in the background with a normal priority. Background transfers use the idle network
bandwidth of the client computer to transfer files.
- Low: Transfers the job in the background with a low priority. Background transfers use the idle network bandw
idth of the client to transfer files. This is the lowest background priority level.

Required? false
Position? named
Default value Normal
Accept pipeline input? false
Accept wildcard characters? false

-ProxyAuthentication
Specifies the authentication mechanism to use at the Web proxy. Possible values are:

- Basic: Basic is a scheme in which the user name and password are sent in clear-text to the server or proxy.
- Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
- NTLM: NTLM is a challenge-response scheme that uses the credentials of the user for authentication in a Windo
ws-based network environment.
- Negotiate (the default): Negotiate is a challenge-response scheme that negotiates with the server or proxy to
determine which scheme to use for authentication. For example, this parameter value allows negotiation to dete
rmine whether the Kerberos protocol or NTLM is used.
- Passport: Passport is a centralized authentication service provided by Microsoft that offers a single logon f
or member sites.

Required? false
Position? named
Default value Negotiate
Accept pipeline input? false
Accept wildcard characters? false

-ProxyBypass
Specifies a list of host names to use for a direct connection. The hosts in the list are tried in order until a
successful connection is achieved. Specifying this parameter bypasses the proxy. If this parameter is used, th
e ProxyUsage parameter must be set to Override; otherwise, an error occurs.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ProxyCredential
Specifies the credentials to use to authenticate the user at the proxy. You can use the Get-Credential cmdlet t
o create a value for this parameter.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ProxyList
Specifies a list of proxies to use. The proxies in the list are tried in order until a successful connection is
achieved. If this parameter is specified and ProxyUsage is set to a value other than Override, an error occurs
.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ProxyUsage
Specifies the proxy usage settings. Possible values are:

- SystemDefault (the default): Use the system default proxy settings.
- NoProxy: Do not use a proxy to transfer files. Use this option when you transfer files within a local area ne
twork (LAN).
- AutoDetect: Automatically detect proxy settings. BITS detects proxy settings for each file in the job.
- Override: Specify the proxies or servers to use. If the ProxyList parameter is also specified, the proxies in
that list are used. If the ProxyBypass parameter is also specified, the servers in that list are used. In both
cases, the first member of the list is used. If the first member is unreachable, the subsequent members are tr
ied until a member is contacted successfully.

Required? false
Position? named
Default value SystemDefault
Accept pipeline input? false
Accept wildcard characters? false

-RetryInterval
Specifies the minimum length of time, in seconds, that BITS waits before trying to transfer the file after BITS
encounters a transient error. The minimum allowed value is 60 seconds. If this value exceeds the RetryTimeout
value from the BitsJob object, BITS will not retry the transfer. Instead, BITS sets the state of the BITS trans
fer job to the Error state.

The default is 600 seconds (10 minutes).

Required? false
Position? named
Default value 600
Accept pipeline input? false
Accept wildcard characters? false

-RetryTimeout
Specifies the length of time, in seconds, that BITS tries to transfer the file after the first transient error
occurs. Setting the retry period to 0 prevents retries and forces the job into the BG_JOB_STATE_ERROR state whe
n an error occurs. If the retry period value exceeds the JobInactivityTimeout Group Policy setting (90-day defa
ult), BITS cancels the job after the JobInactivityTimeout Group Policy setting is exceeded.

The default is 1,209,600 seconds (14 days).

Required? false
Position? named
Default value 1209600
Accept pipeline input? false
Accept wildcard characters? false

-Source
Specifies the source location and the names of the files that you want to transfer. The source file names are p
aired with the corresponding destination file names. For example, the first file name specified in the Source p
arameter corresponds to the first file name in the Destination parameter, and the second file name in the Sourc
e parameter corresponds to the second file name in the Destination parameter. The Source and Destination param
eters must have the same number of elements; otherwise, the command produces an error. You can use standard wil
dcard characters such as the asterisk (*) and the question mark (?). Or, you can use a range operator such as "
[a-r]".

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Suspended []
Suspends the BITS transfer job. If the Suspended parameter is not specified, the job automatically begins the t
ransfer job. If the Suspended parameter is specified, the command prompt returns immediately after the BITS tra
nsfer job is created. You can use the Resume-BitsTransfer cmdlet to start the transfer job.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-TransferType
Specifies the BITS transfer job type. Possible values are:

- Download (the default): Specifies that the transfer job downloads files to the client computer.
- Upload: Specifies that the transfer job uploads a file to the server.
- UploadReply: Specifies that the transfer job uploads a file to the server and receives a reply file from the
server.

Required? false
Position? named
Default value Download
Accept pipeline input? false
Accept wildcard characters? false

-Confirm []
Prompts you for confirmation before executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WhatIf []
Describes what would happen if you executed the command without actually executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
None
This cmdlet does not accept and input.


OUTPUTS
Microsoft.BackgroundIntelligentTransfer.Management.BitsJob
When called with the Asynchronous parameter, this cmdlet passes the BitsJob object that is associated with the
new BITS transfer job as output. Otherwise, no output is generated.


NOTES


You can cancel a transfer job that is running in synchronous mode (foreground priority) by pressing CTRL+C.

If the BITS service is stopped during a synchronous file transfer job, then file transfer job will fail with an
error and the file transfer job will not get removed from the BitsTransfer queue. The file transfer job remain
ing in the BitsTransfer queue can be viewed using the Get-BitsTransfer cmdlet. The file transfer job that remai
ns in the BitsTransfer queue can removed using the Remove-BitsTransfer cmdlet. Once the BITS service is restar
ted, the file transfer job will recover and resume the file transfer job, unless the file transfer job has been
removed in the interim.


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

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


Description
-----------
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 h
ttp://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


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

The command imports the source and destination file locations and then pipes the locations to the Start-BitsTransf
er command. The Start-BitsTransfer command creates a new BITS transfer job, adds the files to a single job, and the
n 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 3 --------------------------

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


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

Important: The Start-BitsTransfer cmdlet lets you download multiple files from a server to a client computer, but i
t does not typically let you upload multiple files from a client computer to a server. It is possible to work aroun
d this limitation by using the Import-CSV cmdlet to pipe the output to the Start-BitsTransfer cmdlet. If you need t
o 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/testfil
e1.txt -Destination c:\clienttestdir\testfile1.txt, c:\clienttestdir\testfile1.txt


Description
-----------
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/ser
vertestdir/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-Credential
New-FileTransfer -DisplayName MyJob -Credential c$ -Source http://server01/servertestdir/testfile1.txt -Destination
c:\clienttestdir\testfile1.txt


Description
-----------
These commands create a new BITS transfer job that downloads a file from a server by using a specific set of creden
tials.

The first command retrieves a set of credentials from the user by calling the Get-Credential cmdlet. The returned P
SCredential 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/servertestd
ir/testfile1.txt file to the client. The specified credentials are used to authenticate the user at the server. Add
itionally, 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


Description
-----------
This command creates a new BITS transfer job that downloads multiple files from a server. The files will be downloa
ded 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, adds the files to a single job, and then transfer
s 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\


Description
-----------
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 tr
ansferred 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 roo
ted path, or an implicit directory (the current directory). Additionally, the destination files cannot be renamed b
y 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


Description
-----------
This command creates a new BITS transfer job that uploads multiple files from a client.

The command imports the source and destination file locations and then pipes them to to the Start-BitsTransfer com
mand. The Start-BitsTransfer command creates a new BITS transfer job, adds the files to a single job, and then tran
sfers them sequentially to the client.

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






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkId=141435
Add-BitsFile
Complete-BitsTransfer
Get-BitsTransfer
Remove-BitsTransfer
Resume-BitsTransfer
Set-BitsTransfer
Suspend-BitsTransfer