BITS IIS Extension Properties
Background Intelligent Transfer Service (BITS) uses an ISAPI to extend IIS to support upload jobs. The following table lists the properties that BITS adds to the IIS metabase for the virtual directory component. BITS uses these properties to determine how to upload the files. The BITS IIS extension properties are inheritable, except for BITSUploadEnabled.
| Property | Description |
|---|---|
| BITSUploadEnabledData type: Boolean |
Indicates whether BITS uploads are enabled on the virtual directory. If the setting is not present or is 0, BITS uploads are disabled. This is a read-only property. To set this property, call the EnableBITSUploads or DisableBITSUploads method of the IBITSExtensionSetup interface. |
| BITSSessionTimeoutData type: DWORD |
Number of seconds the connection is maintained if no progress is made uploading the file; the timer is reset when progress is made. BITS closes the connection if the time-out is reached and cleans up data associated with the session. Setting a short session time-out can be an issue for upload-reply jobs because the reply is only downloaded when the user is logged on and connected to the network. It is possible for the session to time out before the reply is downloaded, in which case the session is canceled and the reply file is deleted. Note that BITS cancels the job if the JobInactivityTimeout Group Policy value (default is 90 days) is reached, regardless of this setting. Default value is 1,209,600 (14 days). |
| BITSMaximumUploadSizeData type: String |
Maximum number of bytes that can be uploaded per job. Specify the maximum number of bytes as a decimal string; the string value must be less than or equal to "1844674407370955". An empty string is the same as specifying "1844674407370955". Default value is an empty string. Note: In IIS 7, the default upload limit is 30 million bytes. The value of the BITSMaximumUploadSize property cannot exceed the IIS limit. For details and information on changing the IIS default, see KB942074. |
| BITSServerNotificationTypeData type: DWORD |
Specifies how to send the upload file to the server application. The possible values are: 0, 1, and 2. A value of 0 means the file is not sent to the server application. BITS puts the upload file in the directory specified in the remote name (the remote name specified when you added the file to the job) without notifying the server application. If the file currently exists in the destination directory, it is replaced with the upload file. A value of 1 means BITS passes the location of the upload file to the server application specified in the BITSServerNotificationURL property. The server application processes the file and generates a reply file, if needed. By default, BITS removes the upload and reply files from the server after it receives the response from the server application. To have BITS copy the upload file to the location specified by the remote file name in the job, include the BITS-Copy-File-To-Destination header in your response. If you do not include the header and you want to save the upload and reply files, you must copy the upload and reply files to a new location before responding. A value of 2 means BITS passes the upload file in the body of the request to the server application specified in the BITSServerNotificationURL property. The server application processes the file and passes back the reply in the body of the response, if needed. For details on the request and response headers, see Notification Protocol for Server Applications. The server application must provide a response within five minutes. If the server application does not reply within five minutes, the job enters the transient error state. When the retry delay expires, the BITS server will send another notification to the server application (the server application should be written to handle duplicate notifications).BITS 1.5: The notification time-out is 30 seconds. Default value is 0. |
| BITSServerNotificationURLData type: String |
Optional. Contains the URL of the server application to which BITS posts the upload file. You must specify a URL if the value of the BITSServerNotificationType property is 1 or 2. The URL is limited to 2,200 characters, not including the null terminator. The URL must be an HTTP URL; BITS does not support HTTPS notification URLs. If the URL is not available at the time of upload, BITS will retry the upload until the notification URL exists or until the retry period expires. Note that if the remote name specified in the job contains a query string, the query string is appended to the URL that you specify. For example, if the remote name contains https://myserver/myvdir/subdir/file.asp?ACCOUNT=86433 and you specify the BITSServerNotificationURL setting as https://otherserver/myvdir2/bag.asp, the URL to which BITS posts is https://otherserver/myvdir2/bag.asp?ACCOUNT=86433. If the original URL is https://myserver/myvdir/file.txt and the notification URL is myasp.asp, BITS uses http//myserver/myvdir/myasp.asp as the notification URL. If the path and file name portion of the URL contains Unicode characters not in common to the code page on both the client and server, the URL translation will fail on the server and the BITS job will be placed in the error state. If the server portion of the URL contains Unicode characters, you must encode the server portion using Internationalized Domain Names (IDN). |
| BITSHostIdData Type: String |
Set this property if the server installation is a web farm that does not use shared storage. Specify the server name or IP address of the server to reconnect to after the upload process is interrupted. Typically, you specify the name of the server you are configuring. The URL is limited to 300 characters, not including the null terminator. If you do not specify this property and the upload process is interrupted, it is possible that BITS will resume the job on another server in the farm. However, the previous server still contains the partial upload file from before the interruption. BITS removes the partial file after the BITSSessionTimeout expires. Note: Do not use the BITSHostId property if SSL is used in a web farm that uses Network Load Balancing (NLB) or DNS names with multiple IP addresses, unless you include the cluster name and individual server names in the certificate. (If the server name specified in BITSHostId does not match the common name on the certificate, the job will fail.) Instead, for NLB, set the Affinity parameter to Single to ensure that the client communicates with the same server in the future. |
| BITSHostIdFallbackTimeoutData type: DWORD |
Number of seconds the BITS client tries to reconnect to the BITSHostId server name before reverting to the host name specified in the remote file name of the job. The timer begins when BITS is unable to connect to the BITSHostId server. The timer is reset when the client successfully connects to the server. Note that the no progress timeout value of the job (see IBackgroundCopyJob::SetNoProgressTimeout) should be longer than this timeout value. If not, the job will fail before fallback timeout value expires. Set this property only if you set the BITSHostId property. Default value is 86,400 (1 day). |
| BITSAllowOverwritesData type: Integer |
Indicates whether an upload file can overwrite an existing file with the same name. The upload file overwrites the existing file if BITSAllowOverwrites is 1. Default value is 0. IIS 6.0: You can set this property only from a script, you cannot set it using the BITS extension properties page in the IIS user interface. |
| BITSCleanupUseDefaultData type: Boolean |
Indicates whether the cleanup task uses the default schedules. By default, the cleanup task is run every 12 hours. Set to 1 to use the default schedule; otherwise, 0 to specify a schedule. To specify a schedule, use the BITSCleanupCount and BITSCleanupUnits properties. The cleanup task cleans up the virtual directory by deleting jobs that have not been modified within the session time-out period (see BITSSessionTimeout). The default is 1 use the default schedule. IIS 6.0: Not supported. |
| BITSCleanupCountData type: Integer |
Specifies the interval to wait between running the cleanup task. The interval that you can specify depends on the units. For possible interval values, see the BITSCleanupUnits property. This property is ignored if BITSCleanupUseDefault is 0. IIS 6.0: Not supported. |
| BITSCleanupUnitsData type: Integer |
Specifies the units for the cleanup interval specified in the BITSCleanupCount property. This property is ignored if BITSCleanupUseDefault is 0. The possible values are:
1: The units are hours. This is the default. Possible values are 1 to 24. 2: The units are days. Possible values are 1 to 360. IIS 6.0: Not supported. |
| BITSNumberOfSessionsLimitData type: Integer |
Limits the number of upload sessions that can exist concurrently for a user. If the number of sessions for a user is more than this limit, when the cleanup task runs it will delete the most recent sessions until the number of sessions for the user is below the limit. The default is 50 sessions. IIS 6.0: Not supported. |
| BITSSessionLimitEnableData type: Boolean |
Indicates whether BITS limits the number of upload sessions per user. If the setting is not present or is 0, the limit is disabled. To specify the limit, set the BITSNumberOfSessionsLimit property. The default is 1. IIS 6.0: Not supported. |
The following example shows how to set the BITS IIS extension properties using Windows Script Host. If the virtual directory points to a remote share, also set the UNCUserName and UNCPassword IIS properties.
if (WScript.Arguments.length < 2)
{
WScript.Echo("Usage: bitsvdir virtual_directory local_directory");
WScript.Quit(1);
}
VirtualDirectoryName = WScript.Arguments(0);
LocalDirectoryName = WScript.Arguments(1);
ServerObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT");
VirtualDir = ServerObj.Create("IIsWebVirtualDir", VirtualDirectoryName );
VirtualDir.Path = LocalDirectoryName;
VirtualDir.AppIsolated = 0;
VirtualDir.AccessScript = true;
VirtualDir.AccessRead = false;
VirtualDir.AccessWrite = false;
VirtualDir.SetInfo();
// Set BITS specific IIS configuration settings
VirtualDir.EnableBITSUploads();
VirtualDir.BITSMaximumUploadSize = "4294967296";
VirtualDir.SetInfo();
WScript.Echo( "Created virtual directory " + VirtualDirectoryName +
" with a local directory of " + LocalDirectoryName );
WScript.Quit( 0 );