Create 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 int]
[-RetryTimeout int] [-Suspended] [-TransferType string]
[-Confirm] [-WhatIf] [CommonParameters]
Key
-BitsJob BitsJob[]
The BITS transfer job(s) to modify.
Pipe a value to this parameter from other cmdlets that return BitsJob objects, such as Get-BitsTransfer.
-Asynchronous
Allow the BITS transfer job to be created and then processed in the background.
The command prompt reappears immediately after the BITS transfer job is created.
The returned BitsJob object can be used to monitor job status and progress.
-Authentication string
The authentication mechanism to be used at the server.
Possible values:
Basic Send the username and password in clear text to the server or proxy.
Digest A challenge-response scheme using a server-specified data string.
NTLM A challenge-response scheme using the Windows credentials of the
user for domain authentication.
Negotiate A challenge-response scheme that negotiates with the server or proxy to
determine which scheme to use. For example: Kerberos or NTLM.
Passport Use Windows Live ID as the authentication mechanism (live.com).
-Credential PSCredential
The credentials to use to authenticate the user at the server.
The default is the current user. Type a user name, such as "User64", "Domain64\User64"
or "User@example.com". Or use Get-Credential to create the value for this parameter.
When you type a user name, you will be prompted for a password.
-Description string
Up to 1024 characters.
-Destination string[]
The destination location and the names of the files to transfer.
The destination names are paired with the corresponding source file names.
For example, the first file name specified in the -Source parameter corresponds to the
first file name in the -Destination parameter, and the second file name in the -Source
parameter corresponds to the second file name in the Destination parameter.
The Source and Destination parameters must have the same number of elements.
-DisplayName string
The display name provides a user-friendly way to differentiate BITS transfer jobs.
-Priority string
Set the priority of the BITS transfer job, which affects bandwidth usage.
Background transfers use the idle network bandwidth of the client computer to transfer files.
valid values:
Foreground Transfer the job in the foreground. (highest priority)
Foreground transfers compete for network bandwidth with other applications,
which can impede the user's overall network experience.
However, if Start-BitsTransfer is being used interactively, this is likely the best option.
High Transfer the job in the background with a high priority.
Normal Transfer the job in the background with a normal priority.
Low Transfer the job in the background with a low priority.(lowest priority)
-ProxyAuthentication string
The authentication mechanism to be used at the server.
Possible values:
Basic Send the username and password in clear text to the server or proxy.
Digest A challenge-response scheme using a server-specified data string.
NTLM A challenge-response scheme using the Windows credentials of the
user for domain authentication.
Negotiate A challenge-response scheme that negotiates with the server or proxy to
determine which scheme to use. For example: Kerberos or NTLM.
Passport Use Windows Live ID as the authentication mechanism (live.com).
-ProxyBypass string[]
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, the -ProxyUsage parameter must be set to Override.
-ProxyCredential PSCredential
The credentials to use to authenticate the user at the proxy.
Use Get-Credential to create a value for this parameter.
-ProxyList Uri[]
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 used, the -ProxyUsage parameter must be set to Override.
-ProxyUsage string
The proxy usage settings. Possible values:
SystemDefault Use the system default proxy settings.
NoProxy Do not use a proxy to transfer the files.
Use this option to transfer files within a local area network (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 tried until a member is contacted successfully.
-RetryInterval int
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 transfer job to the Error state. The default is 600 seconds (10 minutes).
-RetryTimeout int
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.
If the retry period value exceeds the JobInactivityTimeout Group Policy setting (90-day default),
BITS cancels the job. The default value is 1,209,600 seconds (14 days).
-Source string[]
The source location and the names of the files to transfer.
The source file names are paired with the corresponding destination file names. For example,
the first file name specified in the -Source parameter corresponds to the first file name in
the -Destination parameter, and the second file name in the -Source parameter corresponds to
the second file name in the -Destination parameter.
The Source and Destination parameters must have the same number of elements.
Accepts standard wildcard characters asterisk (*) and question mark (?).
Or you can use a range operator such as "[a-r]".
-Suspended
Suspend the BITS transfer job.
If the Suspended parameter is not specified, the job automatically begins the transfer job.
If the Suspended parameter is specified, the command prompt returns immediately after the
BITS transfer job is created. You can use Resume-BitsTransfer to start the transfer job.
-TransferType string
The BITS transfer job type. Possible values are:
Download Download files to the client computer.
Upload Upload a file to the server.
UploadReply Upload a file to the server and receive a reply file from the server.
-Confirm
Prompt for confirmation before executing the command.
-WhatIf
Describe what would happen if you executed the command, without actually executing the command.
CommonParameters:
-Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer -OutVariable.
Start-BitsTransfer 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. To upload more than one file, pipe the output from Import-CSV to Add-BitsFile. Or, consider using a cabinet file (.cab) or a compressed file (.zip).
Examples
Create a new BITS transfer job that downloads a file from a server:
PS C:\> Start-BitsTransfer -Source http://server64/demodir/file1.txt -Destination c:\demo\file1.txt
Or in short form:
PS C:\> Start-BitsTransfer http://server64/demodir/file1.txt c:\demo\file1.txt
Create a new BITS transfer job that downloads multiple files from a server:
PS C:\> Import-CSV filelist.txt | Start-BitsTransfer
filelist.txt
Source, Destination
http://server64/demodir/file1.txt, c:\demo\file1.txt
http://server64/demodir/file2.txt, c:\demo\file2.txt
http://server64/demodir/file3.txt, c:\demo\file3.txt
Create a new BITS transfer job that uploads a file to a server:
PS C:\> Start-BitsTransfer -Source c:\demo\file1.txt -Destination http://server64/demodir/file1.txt -TransferType Upload
Create a new BITS transfer job that downloads two files from a server:
PS C:\> Start-BitsTransfer -Source http://server64/demodir/file1.txt, http://server64/demodir/file2.txt -Destination c:\demo\file1.txt, c:\demo\file2.txt
Download multiple files from a server:
PS C:\> Start-BitsTransfer -Source http://server64/demodir/*.* -Destination c:\demo\
Download a file using a specific set of credentials:
PS C:\> $c = Get-Credential
Start-BitsTransfer -DisplayName MyJob -Credential $c -Source http://server64/demodir/file1.txt -Destination c:\demo\file1.txt
“It is harder to conceal ignorance than to acquire knowledge” ~ Arnold H. Glasgow
Related PowerShell Cmdlets:
Complete-BitsTransfer - Complete a BITS transfer.
Get-BitsTransfer - Get a single or multiple BITS transfer.
BITS PowerShell cmdlets