Using the WinHTTP Proxy Configuration Utility

MSXML 5.0 SDK

previous page next page
Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - XML Reference

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 download the proxy configuration utility, go the Other ResourcesXML Development Center.
    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"

See Also

IServerXMLHTTPRequest/ServerXMLHTTP Members

Applies To: IServerXMLHTTPRequest/ServerXMLHTTP

previous page start next page