Using the WinHTTP Proxy Configuration Utility
The WinHTTP proxy configuration utility, proxycfg.exe, configures WinHTTP to access HTTP and HTTPS servers through a proxy server. Because the ServerXMLHTTP object depends on WinHTTP proxy settings, an administrator can use the proxycfg.exe utility as part of the deployment and installation process of an application that uses WinHTTP. The administrator who runs proxycfg.exe must have local administrator privileges so that proxycfg.exe can update the registry of the local computer. WinHTTP proxy settings are per-machine, not per-user.
Note
WinHTTP proxy settings are separate from the proxy settings in Microsoft® Internet Explorer.
Configuration of WinHTTP proxy settings must be done using the proxycfg.exe utility; these settings cannot be configured through Control Panel. With the proxycfg.exe utility, an administrator can also specify an optional list of host names to bypass the proxy server and be accessed directly. The proxycfg.exe tool can also configure WinHTTP to access all servers directly.
To download the proxy configuration utility
To learn more about how to begin using the proxy configuration utility, search Microsoft.com for the following Knowledge Base article and refer to it:
- 289481 - INFO: You May Need to Run ProxyCfg Utility for ServerXMLHTTP to Work.
Important
After using proxycfg.exe to update the registry, the previous settings cannot be restored.
Usage
The following examples show the syntax used for various commands in the proxycfg.exe utility.
proxycfg
This command displays the current WinHTTP proxy settings.
proxycfg -d
This command specifies that all HTTP and HTTPS servers should be accessed directly. Use this command if there is no proxy server.
proxycfg -p proxy-server-list optional-bypass-list
This command specifies one or more proxy servers, and an optional list of hosts that should be accessed directly. If a proxy server is not specified for a given protocol and that server is not in the bypass list, the -p option specifies that the server cannot be accessed at all.
proxycfg -d -p proxy-server-list optional-bypass-list
This command specifies one or more proxy servers, and an optional list of hosts that should be accessed directly. If a proxy server is not specified for the given protocol, the -d option specifies that the server should be accessed directly instead.
proxycfg -u
This command imports the Internet Explorer proxy settings of the current user. WinHTTP does not support auto-discovery and configuration script-based proxy settings.
The following table describes how to use both the proxy-server-list and optional-bypass-list parameters.
| Parameter | Description of use |
|---|---|
proxy-server-list |
Proxies are specified in a space-delimited string. The proxy listings can contain the port number used to access the proxy. Proxy servers can be listed to use a specific protocol. The valid protocols are HTTP or HTTPS. The syntax for a proxy listing that specifies a protocol is: "protocol=http://proxy_name"where protocol is either http or https and proxy_name is the name of the proxy server. For example, the string, "http=http://http_proxy_name:80", specifies that the protocol is HTTP, the name of the proxy server is http_proxy_name, and the port number for this server is 80. An example of a proxy listing that specifies the HTTPS protocol is "https=http://https_proxy_name".If the proxy server uses the default port number for the protocol, the port number can be omitted. If a proxy name is listed by itself, the proxycfg.exe utility uses that proxy as the default proxy for any protocols that do not have a proxy specified. For example, the listing, "http=http://http_proxy other_proxy", specifies to use the http_proxy server for any HTTP operations and the other_proxy server for any HTTPS operations. |
optional-bypass-list |
This list contains host names or IP addresses that are locally known. This list can contain wildcards, "*", that cause the application to bypass the proxy server for addresses that fit the specified pattern. For example, both "*.microsoft.com" and "*.org" are acceptable wildcard patterns. Wildcard characters must be the left-most characters in the list, so "myserver.*" is not supported. To list multiple addresses and host names, separate them with blank spaces or semicolons in the proxy bypass string. If the "<local>" macro is specified, the function bypasses any host name that does not contain a period. |
Examples
The following is the most common command used with the proxycfg.exe utility. This command specifies to use the proxy server named "itgproxy" to access both HTTP and HTTPS servers, and also bypass any host names that do not contain a period. In this case, the -d option has no effect.
proxycfg -d -p itgproxy "<local>"
Compare the previous command to the following command which specifies to use the server named "itgproxy" to access both HTTP and HTTPS servers, and not to bypass any servers.
proxycfg -p itgproxy
The following is an example of a more complex command used by the proxycfg.exe utility. This command specifies to use the server named "http_proxy" to access HTTP servers and the server named "https_proxy" to access HTTPS servers. This command also specifies that local intranet sites (for example, host names that do not contain a period) and any site in the "*.microsoft.com" domain bypass the proxy.
proxycfg -p "http=http_proxy https=https_proxy" "<local>;*.microsoft.com"
Applies to
IServerXMLHTTPRequest-ServerXMLHTTP