Creates a new Background Intelligent Transfer Service (BITS) transfer job.
Syntax
1 |
Start-BitsTransfer [-Source] <string[]> [[-Destination] <string[]>] [-Asynchronous] [-Authentication <string>] [-Credential <pscredential>] [-Description <string>] [-DisplayName </string><string>] [-Priority </string><string>] [-ProxyAuthentication </string><string>] [-ProxyBypass <string[]>] [-ProxyCredential <pscredential>] [-ProxyList <Uri[]>] [-ProxyUsage <string>] [-RetryInterval <int>] [-RetryTimeout </int><int>] [-Suspended] [-TransferType <string>] [-Confirm] [-WhatIf] [<commonparameters>]</commonparameters></string></int></string></pscredential></string></pscredential></string> |
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).
Parameters
-Asynchronous
Allows 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 status and progress.
-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 Windows-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 determine whether the Kerberos protocol or NTLM is used.
– Passport: Passport is a centralized authentication service provided by Microsoft that offers a single logon for member sites.
-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 «[email protected]». Or, use the Get-Credential cmdlet to create the value for this parameter. When you type a user name, you will be prompted for a password.
-Description
Describes the BITS transfer job. The description is limited to 1,024 characters.
-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 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; otherwise, the command produces an error.
-DisplayName
Specifies a display name for the BITS transfer job. The display name provides a user-friendly way to differentiate BITS transfer jobs.
-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-BitsTransfer 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 bandwidth 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 bandwidth of the client to transfer files. This is the lowest background priority level.
-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 Windows-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 determine whether the Kerberos protocol or NTLM is used.
– Passport: Passport is a centralized authentication service provided by Microsoft that offers a single logon for member sites.
-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, the ProxyUsage parameter must be set to Override; otherwise, an error occurs.
-ProxyCredential
Specifies the credentials to use to authenticate the user at the proxy. You can use the Get-Credential cmdlet to create a value for this parameter.
-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.
-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 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
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 transfer job to the Error state.
The default is 600 seconds (10 minutes).
-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 when an error occurs. If the retry period value exceeds the JobInactivityTimeout Group Policy setting (90-day default), BITS cancels the job after the JobInactivityTimeout Group Policy setting is exceeded.
The default is 1,209,600 seconds (14 days).
-Source
Specifies the source location and the names of the files that you want 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; otherwise, the command produces an error. You can use standard wildcard characters such as the asterisk (*) and the question mark (?). Or, you can use a range operator such as «[a-r]».
-Suspended
Suspends 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 the Resume-BitsTransfer cmdlet to start the transfer job.
-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.
-Confirm
Prompts you for confirmation before executing the command.
-WhatIf
Describes what would happen if you executed the command without actually executing the command.
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.
Inputs and Outputs
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.
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 remaining in the BitsTransfer queue can be viewed using the Get-BitsTransfer cmdlet. The file transfer job that remains in the BitsTransfer queue can removed using the Remove-BitsTransfer cmdlet. Once the BITS service is restarted, the file transfer job will recover and resume the file transfer job, unless the file transfer job has been removed in the interim.