Start-BitsTransfer

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:

Complete-BitsTransfer - Complete a BITS transfer
Get-BitsTransfer - Get a single or multiple BITS transfer
BITS PowerShell cmdlets


© Copyright SS64.com 1999-2013
Some rights reserved