Ferramenta de configuração de proxy ProxyCfg.exe

Este tópico explica o uso da ferramenta de configuração de proxy do Microsoft Windows HTTP Services (WinHTTP).ProxyCfg.exe

Há duas maneiras de acessar servidores HTTP e HTTPS (Secure Hypertext Transfer Protocol) por meio de um proxy usando o Microsoft Windows HTTP Services (WinHTTP). Primeiro, você pode especificar configurações de proxy de dentro de seu aplicativo WinHTTP. Em segundo lugar, você pode especificar as configurações de proxy padrão de fora do aplicativo usando o utilitário de configuração de proxy localizado no diretório %windir%\system32.

Você pode definir programaticamente os dados de proxy de dentro de seu aplicativo ou script. Se você estiver escrevendo um aplicativo usando a API WinHTTP, use uma das duas técnicas a seguir para alterar as configurações de proxy.

• Use a função WinHttpOpen. Especifique o tipo de acesso no segundo parâmetro, o nome do proxy no terceiro parâmetro e uma lista de bypass no quarto parâmetro. O exemplo a seguir mostra como a função WinHttpOpen pode ser usada para definir dados de proxy.

  hSession = WinHttpOpen( L"WinHTTP Example/1.0",  
                          WINHTTP_ACCESS_TYPE_NAMED_PROXY,
                          L"proxy_name", 
                          L"<local>", 
                          0);
  

• Use a função WinHttpSetOption. O sinalizador WINHTTP_OPTION_PROXY permite especificar configurações de proxy com uma estrutura WINHTTP_PROXY_INFO. O exemplo a seguir mostra como a função WinHttpOpen pode ser usada para definir dados de proxy.

  WINHTTP_PROXY_INFO proxyInfo;
  proxyInfo.dwAccessType = WINHTTP_ACCESS_TYPE_NAMED_PROXY;
  proxyInfo.lpszProxy = L"proxy_name";
  proxyInfo.lpszProxyBypass = L"<local>";
  
  // Set the proxy information for this session.
  WinHttpSetOption( hSession, 
                    WINHTTP_OPTION_PROXY, 
                    &proxyInfo, 
                    sizeof(proxyInfo));
  

Se você estiver escrevendo um script ou um aplicativo usando o objeto WinHttpRequest, use a técnica a seguir para alterar as configurações de proxy.

• Use o método SetProxy. Especifique o tipo de acesso no primeiro parâmetro, o nome do proxy no segundo parâmetro e uma lista de bypass no terceiro parâmetro. O exemplo a seguir mostra como o método SetProxy pode ser usado no script para definir dados de proxy.

  WinHttpReq.SetProxy( HTTPREQUEST_PROXYSETTING_PROXY, 
                       "proxy_server:80", 
                       "*.microsoft.com");
  

Para especificar as configurações padrão e eliminar a necessidade de usar o método SetProxy ou a função WinHttpSetOption, use o utilitário de configuração de proxy. Com esse utilitário, você pode especificar que o aplicativo acesse uma rede diretamente, por meio de um proxy ou por meio de uma combinação de acesso direto e proxy especificando uma lista de bypass. Quando você usa a API WinHTTP, a ferramenta de configuração de proxy só determina as configurações quando você passa o sinalizador WINHTTP_ACCESS_TYPE_DEFAULT para a API WinHttpOpen. O objeto WinHttpRequest usa as definições da ferramenta de configuração de proxy por padrão.

As configurações de proxy para WinHTTP não são as configurações de proxy para o Microsoft Internet Explorer. Não é possível definir as configurações de proxy para WinHTTP no painel de controle do Microsoft Windows. Usar o utilitário de configuração de proxy WinHTTP não altera as configurações que você usa para o Internet Explorer.

Parâmetros de linha de comando

A tabela a seguir lista os parâmetros de linha de comando disponíveis para uso com a ferramenta 'ProxyCfg.exe''.

Você pode especificar proxies em uma cadeia de caracteres delimitada por espaço. As listagens de proxy podem conter o número da porta que é usado para acessar o proxy. Para listar um proxy para um protocolo específico, a cadeia de caracteres deve seguir o formato, <protocol>=https://< proxy_name>. Os protocolos válidos são HTTP e HTTPS. Por exemplo, para listar um proxy HTTP, uma cadeia de caracteres válida é http=https://http_proxy_name:80, em que http_proxy_name é o nome do servidor proxy, e 80 é o número da porta que você deve usar para acessar o proxy. Se o proxy usar o número de porta padrão para esse protocolo, você poderá omitir o número da porta. Se um nome de proxy estiver listado por si só, você poderá usá-lo como proxy padrão para quaisquer protocolos que não tenham um proxy especificado. Por exemplo, http=https://http_proxy other_proxy usa http_proxy para qualquer operação HTTP, enquanto o protocolo HTTPS usa o proxy chamado other_proxy.

Você pode listar nomes de host conhecidos localmente ou endereços IP na lista de bypass de proxy. Essa lista pode conter curingas, como "*", que fazem com que o aplicativo ignore o servidor proxy para endereços que se encaixam no padrão especificado, por exemplo, "*.microsoft.com" ou "*.org". Os caracteres curinga devem ser os caracteres mais à esquerda na lista. Por exemplo, não há suporte para "aaa.*". Para listar vários endereços e nomes de host, separe-os com espaços em branco ou ponto-e-vírgula na cadeia de caracteres de desvio de proxy. Se você especificar a macro <local>, a função ignorará qualquer nome de host que não contenha um ponto.

Uso

Para usar a ferramenta de configuração de proxy, abra uma janela de prompt de comando e execute o utilitário de configuração de proxy com os parâmetros de linha de comando apropriados. A seção a seguir fornece exemplos de sintaxe.

Exemplo de sintaxe

Exemplo 1: usar um proxy somente para recursos externos

Veja a seguir o uso mais comum para Proxycfg.exe. Este comando especifica que os servidores HTTP e HTTPS são acessados por meio do servidor proxy chamado "proxy_server", exceto para nomes de host que não contêm um ponto.

proxycfg -p proxy_server "<local>"

Exemplo 2: usar um proxy para todos os recursos

O exemplo a seguir especifica que os servidores HTTP e HTTPS são acessados por meio do servidor proxy chamado "proxy_server". Nenhuma lista de bypass é especificada.

proxycfg -p proxy_server

Exemplo 3: usar um proxy diferente para recursos seguros

O exemplo a seguir especifica que os servidores HTTP são acessados por meio do proxy http_proxy e os servidores HTTPS são acessados por meio https_proxy. Sites de intranet local e qualquer site no domínio *.microsoft.com ignoram o proxy.

proxycfg -p "http=http_proxy https=https_proxy" "<local>;*.microsoft.com"

Removendo ProxyCfg.exe

Depois de usar a ferramenta de configuração de proxy, você não pode restaurar suas configurações de proxy originais. No entanto, se necessário, você pode remover as configurações do Registro que o utilitário cria. Para remover as entradas do Registro que ProxyCfg.exe cria, você deve excluir o valor WinHttpSettings da seguinte chave do Registro.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\Connections\WinHttpSettings

A exclusão do valor WinHttpSettings remove todas as configurações de proxy.

ProxyCfg.exe e autenticação

O utilitário de configuração de proxy define a política de autenticação padrão. Como você não deve executar a autenticação NTLM com hosts não confiáveis, por padrão, a autenticação NTLM só ocorre automaticamente com hosts na lista de desvio de proxy. Se não houver proxy, você ainda poderá usar ProxyCfg.exe para especificar uma lista de bypass de hosts confiáveis para executar a autenticação NTLM. Um nome de proxy é necessário ao usar ProxyCfg.exe para essa finalidade, mas você pode usar qualquer cadeia de caracteres válida no lugar de um nome de proxy real.

Para obter mais informações sobre a diretiva de logon automático, consulte a Política de logon automático.