Skip to content

Commit

Permalink
Update Azure SDK proxy server configuration doc (#43593)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
scottaddie authored Nov 18, 2024
1 parent 5b23ea8 commit 11abe70
Show file tree
Hide file tree
Showing 6 changed files with 124 additions and 53 deletions.
4 changes: 4 additions & 0 deletions .openpublishing.redirection.azure.json
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,10 @@
{
"source_path_from_root": "/docs/azure/ai/get-started-app-chat-scaling-with-azure-container-apps.md",
"redirect_url": "/dotnet/ai/get-started-app-chat-scaling-with-azure-container-apps"
},
{
"source_path_from_root": "/docs/azure/sdk/azure-sdk-configure-proxy.md",
"redirect_url": "/dotnet/azure/sdk/configure-proxy"
}
]
}
4 changes: 2 additions & 2 deletions docs/azure/TOC.yml
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,8 @@
href: ./sdk/pagination.md
- name: Unit testing and mocking
href: ./sdk/unit-testing-mocking.md
- name: Configure a proxy server
href: ./sdk/azure-sdk-configure-proxy.md
- name: Configure a proxy
href: ./sdk/configure-proxy.md
- name: Library method types
href: ./sdk/protocol-convenience-methods.md
- name: Packages list
Expand Down
51 changes: 0 additions & 51 deletions docs/azure/sdk/azure-sdk-configure-proxy.md

This file was deleted.

85 changes: 85 additions & 0 deletions docs/azure/sdk/configure-proxy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
title: Configure a proxy when using the Azure SDK for .NET
description: Learn different approaches for configuring a proxy for use with the Azure SDK for .NET client libraries.
ms.topic: conceptual
ms.custom: devx-track-dotnet, engagement-fy23
ms.date: 11/18/2024
---

# 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.

> [!IMPORTANT]
> The following instructions apply only to [libraries with a dependency on Azure.Core](protocol-convenience-methods.md#azure-sdk-client-library-dependency-patterns).
## Configure using code

To programmatically configure a proxy, complete the following steps:

1. Create an <xref:System.Net.Http.HttpClientHandler> object whose `Proxy` property is set.
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.
1. 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:

:::code language="csharp" source="snippets/configure-proxy/Program.cs":::

## 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](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:

- 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](#tab/cmd)

```cmd
rem Non-authenticated HTTP server:
set HTTP_PROXY=http://10.10.1.10:1180
rem Authenticated HTTP server:
set HTTP_PROXY=http://username:[email protected]:1180
rem Non-authenticated HTTPS server:
set HTTPS_PROXY=https://10.10.1.10:1180
rem Authenticated HTTPS server:
set HTTPS_PROXY=https://username:[email protected]:1180
```

### [bash](#tab/bash)

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

# Authenticated HTTP server:
HTTP_PROXY=http://username:[email protected]:1180

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

# Authenticated HTTPS server:
HTTPS_PROXY=https://username:[email protected]:1180
```

---
18 changes: 18 additions & 0 deletions docs/azure/sdk/snippets/configure-proxy/Program.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
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);
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net9.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Azure.Identity" Version="1.13.1" />
<PackageReference Include="Azure.Security.KeyVault.Secrets" Version="4.7.0" />
</ItemGroup>

</Project>

0 comments on commit 11abe70

Please sign in to comment.