Configure a proxy when using the Azure SDK for .NET

If your organization requires the use of a proxy server to access Internet resources, some configuration is required to use the Azure SDK for .NET client libraries. Once configured, the proxy is applied to the underlying HttpClient instance used for HTTP operations.

The proxy can be configured via code or via an environment variable. The approach you choose depends on the desired behavior. Set the appropriate environment variable if you want the proxy to apply globally to all service clients created within the current process. Alternatively, configure the proxy via code to selectively apply the settings to service clients.

Tábhachtach

The following instructions apply only to libraries with a dependency on Azure.Core.

Configure using code

To programmatically configure a proxy, complete the following steps:

1. Create an HttpClientHandler object whose Proxy property is set.
2. Create a service client options object whose Transport property is set to an HttpClientTransport object accepting the HttpClientHandler instance.
3. Pass the service client options object to the service client constructor.

Using the Azure Key Vault Secrets library as an example, you'd have the following code:

C#

using System.Net;
using Azure.Core.Pipeline;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

using HttpClientHandler handler = new()
{
    Proxy = new WebProxy(new Uri("<proxy-url>")),
};

SecretClientOptions options = new()
{
    Transport = new HttpClientTransport(handler),
};
SecretClient client = new(
    new Uri("https://<key-vault-name>.vault.azure.net/"),
    new DefaultAzureCredential(),
    options);

Configure using environment variables

The following table provides an inventory of environment variables that can be set to configure a proxy for use.

Environment variable	Purpose
HTTP_PROXY or http_proxy	The proxy server used on HTTP requests.
HTTPS_PROXY or https_proxy	The proxy server used on HTTPS requests.
ALL_PROXY or all_proxy	The proxy server used for both HTTP and HTTPS requests.
NO_PROXY or no_proxy	A comma-delimited list of hostnames to exclude from proxying.
GATEWAY_INTERFACE	Indicator that the app is running in a Common Gateway Interface (CGI) environment. Example value: CGI/1.1

For a deep understanding of how these environment variables are processed, see the code. Be aware of the following behaviors:

• Each environment variable in the preceding table, except GATEWAY_INTERFACE, can alternatively be defined as lowercase. The lowercase form takes precedence over the uppercase form.`
• If both http_proxy and GATEWAY_INTERFACE are undefined, HTTP_PROXY is used.
• ALL_PROXY is considered only when either an HTTP or an HTTPS proxy is undefined.
• Protocol-specific environment variables take precedence over ALL_PROXY.

The proxy server URL takes the form http[s]://[username:password@]<ip_address_or_hostname>:<port>/, where the username:password combination is optional. To get the IP address or hostname, port, and credentials for your proxy server, consult your network administrator.

The following examples show how to set the appropriate environment variables in command shell (Windows) and bash (Linux/macOS) environments. Setting the appropriate environment variable causes the Azure SDK for .NET libraries to use the proxy server at runtime.

cmd

Windows Command Prompt

rem Non-authenticated HTTP server:
set HTTP_PROXY=http://10.10.1.10:1180

rem Authenticated HTTP server:
set HTTP_PROXY=http://username:password@10.10.1.10:1180

rem Non-authenticated HTTPS server:
set HTTPS_PROXY=https://10.10.1.10:1180

rem Authenticated HTTPS server:
set HTTPS_PROXY=https://username:password@10.10.1.10:1180

bash

Bash

# Non-authenticated HTTP server:
HTTP_PROXY=http://10.10.1.10:1180

# Authenticated HTTP server:
HTTP_PROXY=http://username:password@10.10.1.10:1180

# Non-authenticated HTTPS server:
HTTPS_PROXY=https://10.10.1.10:1180

# Authenticated HTTPS server:
HTTPS_PROXY=https://username:password@10.10.1.10:1180