Start-bitstransfer Proxy

[Imke]

Allof the examples in this topic use the Start-BitsTransfer cmdlet. To use the cmdlet, be sure to import the module first. To install the module, run the following command: Import-Module BitsTransfer. For more information, type Get-Help Start-BitsTransfer at the PowerShell prompt.

When you use *-BitsTransfer cmdlets from within a process that runs in a noninteractive context, such as a Windows service, you may not be able to add files to BITS jobs, which can result in a suspended state. For the job to proceed, the identity that was used to create a transfer job must be logged on. For example, when creating a BITS job in a PowerShell script that was executed as a Task Scheduler job, the BITS transfer will never complete unless the Task Scheduler's task setting "Run only when user is logged on" is enabled.

In the preceding example, the local and remote names of the file are specified in the Source and Destination parameters, respectively. The command prompt returns when the file transfer is complete or when it enters an error state.

Because parameter position is enforced for the Start-BitsTransfer cmdlet, the parameter names do not need to be specified for the Source and Destination parameters. Therefore, this command can be simplified as follows.

The destination path cannot use wildcard characters. The destination path supports relative directories, root paths, or implicit directories (that is, the current directory). Destination files cannot be renamed by using a wildcard character. Additionally, HTTP and HTTPS URLs do not work with wildcards. Wildcards are only valid for UNC paths and local directories.

In the preceding example, a user creates a BITS transfer job to download a file from a server that requires authentication. The user is prompted for credentials, and the Credential parameter passes a credential object to the Start-BitsTransfer cmdlet. The user sets an explicit proxy, and the BITS transfer job uses only the proxies that are defined by the ProxyList parameter. The DisplayName parameter gives the BITS transfer job a unique display name.

In the preceding example, a user creates a BITS transfer job that uploads multiple files from a client. The Import-CSV cmdlet imports the source and destination file locations and pipes them to the Start-BitsTransfer command. The Start-BitsTransfer command creates a new BITS transfer job for each file, adds the files to the job, and then transfers them sequentially to the server.

In the preceding example, the BITS transfer job was assigned to the $Job variable. The files are downloaded sequentially. After the transfer job is complete, the files are immediately available. If $Job.JobState returns "Transferred", the $Job object is sent to the Complete-BitsTransfer cmdlet.

Starting with Windows 10, version 1607, you can run PowerShell Cmdlets, BITSAdmin, or other applications that use the BITS interfaces from a PowerShell Remote command line connected to another machine (physical or virtual). This capability is not available when using a PowerShell Direct command line to a virtual machine on the same physical machine, and it is not available when using WinRM cmdlets.

The example below shows how to use PowerShell Remote to work with asynchronous BITS transfer jobs in a way that allows the job to continue to make progress even when you are not actively connected to the remote session.

The Start-BitsTransfer cmdlet creates a Background Intelligent Transfer Service (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 the download of multiple files from a server to a client computer, but it does not generally support the upload of 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 a cabinet file (.cab) or a compressed file (.zip).

This command creates a 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 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.

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:

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.

This command creates a 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 command prompt returns when the file transfer is complete or enters an error state.

The Start-BitsTransfer cmdlet downloads multiple files from a server to a client computer, but it does not typically 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.

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 and 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.

The second command uses the Credential parameter to pass the PSCredential object that is stored in the $Cred variable to the Start-BitsTransfer cmdlet.A new BITS transfer job is created that downloads the 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.

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 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.

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.

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 format.Finally, it uses the ProxyCredential parameter to specify the credentials of an administrator who has permission to connect to the proxy server.

Indicates that the cmdlet creates and processes BITS transfer job 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.

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.

Specifies an array that contains 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.

3a8082e126