Skip to content

Commit 11abe70

Browse files
scottaddiescottaddie
authored
Update Azure SDK proxy server configuration doc (#43593)
* Explain how to configure a proxy server via code * edits * Document additional env vars * Edits * Edits * Update code * Update ToC * React to feedback * Link to code
1 parent 5b23ea8 commit 11abe70

File tree

6 files changed

+124
-53
lines changed

6 files changed

+124
-53
lines changed

‎.openpublishing.redirection.azure.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,10 @@
119119
{
120120
"source_path_from_root": "/docs/azure/ai/get-started-app-chat-scaling-with-azure-container-apps.md",
121121
"redirect_url": "/dotnet/ai/get-started-app-chat-scaling-with-azure-container-apps"
122+
},
123+
{
124+
"source_path_from_root": "/docs/azure/sdk/azure-sdk-configure-proxy.md",
125+
"redirect_url": "/dotnet/azure/sdk/configure-proxy"
122126
}
123127
]
124128
}

‎docs/azure/TOC.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,8 @@
8989
href: ./sdk/pagination.md
9090
- name: Unit testing and mocking
9191
href: ./sdk/unit-testing-mocking.md
92-
- name: Configure a proxy server
93-
href: ./sdk/azure-sdk-configure-proxy.md
92+
- name: Configure a proxy
93+
href: ./sdk/configure-proxy.md
9494
- name: Library method types
9595
href: ./sdk/protocol-convenience-methods.md
9696
- name: Packages list

‎docs/azure/sdk/azure-sdk-configure-proxy.md

Lines changed: 0 additions & 51 deletions
This file was deleted.

‎docs/azure/sdk/configure-proxy.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Configure a proxy when using the Azure SDK for .NET
3+
description: Learn different approaches for configuring a proxy for use with the Azure SDK for .NET client libraries.
4+
ms.topic: conceptual
5+
ms.custom: devx-track-dotnet, engagement-fy23
6+
ms.date: 11/18/2024
7+
---
8+
9+
# Configure a proxy when using the Azure SDK for .NET
10+
11+
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.
12+
13+
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.
14+
15+
> [!IMPORTANT]
16+
> The following instructions apply only to [libraries with a dependency on Azure.Core](protocol-convenience-methods.md#azure-sdk-client-library-dependency-patterns).
17+
18+
## Configure using code
19+
20+
To programmatically configure a proxy, complete the following steps:
21+
22+
1. Create an <xref:System.Net.Http.HttpClientHandler> object whose `Proxy` property is set.
23+
1. Create a service client options object whose <xref:Azure.Core.ClientOptions.Transport%2A> property is set to an `HttpClientTransport` object accepting the `HttpClientHandler` instance.
24+
1. Pass the service client options object to the service client constructor.
25+
26+
Using the Azure Key Vault Secrets library as an example, you'd have the following code:
27+
28+
:::code language="csharp" source="snippets/configure-proxy/Program.cs":::
29+
30+
## Configure using environment variables
31+
32+
The following table provides an inventory of environment variables that can be set to configure a proxy for use.
33+
34+
| Environment variable | Purpose |
35+
|--------------------------------|-------------------------------------------------------------------------------------------------------------|
36+
| `HTTP_PROXY` or `http_proxy` | The proxy server used on HTTP requests. |
37+
| `HTTPS_PROXY` or `https_proxy` | The proxy server used on HTTPS requests. |
38+
| `ALL_PROXY` or `all_proxy` | The proxy server used for both HTTP and HTTPS requests. |
39+
| `NO_PROXY` or `no_proxy` | A comma-delimited list of hostnames to exclude from proxying. |
40+
| `GATEWAY_INTERFACE` | Indicator that the app is running in a Common Gateway Interface (CGI) environment. Example value: `CGI/1.1` |
41+
42+
For a deep understanding of how these environment variables are processed, see [the code](https://github.com/Azure/azure-sdk-for-net/blob/9aa3b3a44f81bc0be5a4fc86607e0150ba9815d5/sdk/core/Azure.Core/src/Pipeline/Internal/HttpEnvironmentProxy.cs#L31). Be aware of the following behaviors:
43+
44+
- 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.`
45+
- If both `http_proxy` and `GATEWAY_INTERFACE` are undefined, `HTTP_PROXY` is used.
46+
- `ALL_PROXY` is considered only when either an HTTP or an HTTPS proxy is undefined.
47+
- Protocol-specific environment variables take precedence over `ALL_PROXY`.
48+
49+
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.
50+
51+
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.
52+
53+
### [cmd](#tab/cmd)
54+
55+
```cmd
56+
rem Non-authenticated HTTP server:
57+
set HTTP_PROXY=http://10.10.1.10:1180
58+
59+
rem Authenticated HTTP server:
60+
set HTTP_PROXY=http://username:[email protected]:1180
61+
62+
rem Non-authenticated HTTPS server:
63+
set HTTPS_PROXY=https://10.10.1.10:1180
64+
65+
rem Authenticated HTTPS server:
66+
set HTTPS_PROXY=https://username:[email protected]:1180
67+
```
68+
69+
### [bash](#tab/bash)
70+
71+
```bash
72+
# Non-authenticated HTTP server:
73+
HTTP_PROXY=http://10.10.1.10:1180
74+
75+
# Authenticated HTTP server:
76+
HTTP_PROXY=http://username:[email protected]:1180
77+
78+
# Non-authenticated HTTPS server:
79+
HTTPS_PROXY=https://10.10.1.10:1180
80+
81+
# Authenticated HTTPS server:
82+
HTTPS_PROXY=https://username:[email protected]:1180
83+
```
84+
85+
---

‎docs/azure/sdk/snippets/configure-proxy/Program.cs

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
using System.Net;
2+
using Azure.Core.Pipeline;
3+
using Azure.Identity;
4+
using Azure.Security.KeyVault.Secrets;
5+
6+
using HttpClientHandler handler = new()
7+
{
8+
Proxy = new WebProxy(new Uri("<proxy-url>")),
9+
};
10+
11+
SecretClientOptions options = new()
12+
{
13+
Transport = new HttpClientTransport(handler),
14+
};
15+
SecretClient client = new(
16+
new Uri("https://<key-vault-name>.vault.azure.net/"),
17+
new DefaultAzureCredential(),
18+
options);

‎docs/azure/sdk/snippets/configure-proxy/ProxyServerConfiguration.csproj

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net9.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<PackageReference Include="Azure.Identity" Version="1.13.1" />
12+
<PackageReference Include="Azure.Security.KeyVault.Secrets" Version="4.7.0" />
13+
</ItemGroup>
14+
15+
</Project>

0 commit comments

Comments
 (0)