powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Set-BitsTransfer



NAME
Set-BitsTransfer

SYNOPSIS
Modifies the properties of an existing Background Intelligent Transfer Service (BITS) transfer job.

SYNTAX
Set-BitsTransfer [-BitsJob] [-Authentication ] [-Credential ] [-Description ng>] [-DisplayName ] [-Priority ] [-ProxyAuthentication ] [-ProxyBypass ] [-Proxy
Credential ] [-ProxyList ] [-ProxyUsage ] [-RetryInterval ] [-RetryTimeout ]
[-SetOwnerToCurrentUser] [-Confirm] [-WhatIf] []


DESCRIPTION
The Set-BitsTransfer cmdlet modifies the properties of an existing BITS transfer job. You can specify the job that
you want to modify in the BitsJob parameter. Or, you can specify the job by passing it through the pipeline.


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

-BitsJob
Specifies the BITS transfer jobs on which to set properties. You can pipe a value to this parameter from other
cmdlets that return BitsJob objects, such as Get-BitsTransfer.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
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

-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
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, t
he 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 the files. Use this option when you transfer files within a local are
a 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 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. If the retry period value exceeds the JobInactivityTime
out Group Policy setting (90-day default), BITS cancels the job.

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

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

-SetOwnerToCurrentUser []
Sets the owner of the BITS transfer job to the current user.

Required? false
Position? named
Default value
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
Microsoft.BackgroundIntelligentTransfer.Management.BitsJob[]
This cmdlet accepts one or more BitsJob objects as input that populates the BitsJob parameter.


OUTPUTS
Microsoft.BackgroundIntelligentTransfer.Management.BitsJob[]
This cmdlet generates the BitsJob objects that are associated with the BITS transfer jobs that were modified.


NOTES





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

C:\PS>$b = Get-BitsTransfer -JobId 10778CFA-C1D7-4A82-8A9D-80B19224879C
Set-BitsTransfer -BitsJob $b -Priority High


Description
-----------
This command modifies the priority of an existing BITS transfer job.

The first command retrieves the BITS transfer job specified by the JobId parameter and then stores it in the $b var
iable.

The second command uses the BitsJob parameter to pass the BitsJob object stored in the $b variable to the Set-BitsT
ransfer parameter. The Priority parameter is used to set the priority of the BITS transfer job to High.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>Get-BitsTransfer -AllUsers -Name *Microsoft* | Set-BitsTransfer -SetOwnerToCurrentUser


Description
-----------
This command makes the current user the owner of a set of existing BITS transfer jobs.

The output of the Get-BitsTransfer cmdlet is a set of BitsJob objects whose display name contains "Microsoft". This
output is passed to the Set-BitsTransfer cmdlet through the pipeline. The SetOwnerToCurrentUser parameter specifie
s that the owner of each BITS transfer job is the current user.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$b = Get-BitsTransfer -JobId 10778CFA-C1D7-4A82-8A9D-80B19224879C
$c = Get-Credential
Set-BitsTransfer -BitsJob $b -ProxyUsage AutoDetect -ProxyAuthentication $c


Description
-----------
This command changes the proxy settings of an existing BITS transfer job.

The first command retrieves the BITS transfer job identified by the JobId parameter and then stores it in the $b va
riable.

The second command retrieves credentials from the user and then stores them in the $c variable.

The third command uses the BitsJob parameter to pass the BitsJob object stored in the $b variable to the Set-BitsTr
ansfer cmdlet. It uses the ProxyAuthentication parameter to pass the PSCredential object stored in the $c parameter
. The ProxyUsage parameter allows the BITS transfer job to automatically discover the Web proxy server by using the
Web Proxy Autodiscovery Protocol (WPAD) protocol. The supplied set of credentials is used to authenticate the user
at the proxy server.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>Get-BitsTransfer | Set-BitsTransfer -ProxyUsage Override -ProxyList http://proxy1,http://proxy2:81 -ProxyBypa
ss http://directconnect


Description
-----------
This command changes the proxy settings of an existing BITS transfer job.

The output of the Get-BitsTransfer cmdlet is the set of BitsJob objects that are owned by the current user. This ou
tput is piped to the Set-BitsTransfer cmdlet. The Override value that is specified in the ProxyUsage parameter indi
cates that an explicit list of proxy server and bypassed host names will be provided.

The ProxyList parameter specifies two proxy servers. The first server in the list (http://proxy1) is used. If that
connection fails, the command tries the connection by using the second server in the list (http://proxy2:81). If bo
th connections fail, the job fails.

When a list of host names is specified in the ProxyBypass parameter, the connection that is made is a direct connec
tion that does not use a proxy server. In this example, no proxy server is used to add a file to the BITS transfer
queue on the "directconnect" server.






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