From 11abe70b393ef9352fccf08c53c520562b4014e9 Mon Sep 17 00:00:00 2001 From: Scott Addie <10702007+scottaddie@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:43:48 -0600 Subject: [PATCH] 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 --- .openpublishing.redirection.azure.json | 4 + docs/azure/TOC.yml | 4 +- docs/azure/sdk/azure-sdk-configure-proxy.md | 51 ----------- docs/azure/sdk/configure-proxy.md | 85 +++++++++++++++++++ .../sdk/snippets/configure-proxy/Program.cs | 18 ++++ .../ProxyServerConfiguration.csproj | 15 ++++ 6 files changed, 124 insertions(+), 53 deletions(-) delete mode 100644 docs/azure/sdk/azure-sdk-configure-proxy.md create mode 100644 docs/azure/sdk/configure-proxy.md create mode 100644 docs/azure/sdk/snippets/configure-proxy/Program.cs create mode 100644 docs/azure/sdk/snippets/configure-proxy/ProxyServerConfiguration.csproj diff --git a/.openpublishing.redirection.azure.json b/.openpublishing.redirection.azure.json index 6530031c11591..d5f59ae803c4f 100644 --- a/.openpublishing.redirection.azure.json +++ b/.openpublishing.redirection.azure.json @@ -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" } ] } diff --git a/docs/azure/TOC.yml b/docs/azure/TOC.yml index d657e288d98f6..c0f02e227efdd 100644 --- a/docs/azure/TOC.yml +++ b/docs/azure/TOC.yml @@ -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 diff --git a/docs/azure/sdk/azure-sdk-configure-proxy.md b/docs/azure/sdk/azure-sdk-configure-proxy.md deleted file mode 100644 index 3b93d7354fd4a..0000000000000 --- a/docs/azure/sdk/azure-sdk-configure-proxy.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Configure a proxy server when using the Azure SDK for .NET -description: Use HTTP[S]_PROXY environment variables to define a proxy for the Azure SDK for .NET -ms.topic: conceptual -ms.custom: devx-track-dotnet, engagement-fy23 -ms.date: 3/23/2023 ---- - -# Configure a proxy server when using the Azure SDK for .NET - -If your organization requires the use of a proxy server to access internet resources, you will need to set an environment variable with the proxy server information to use the Azure SDK for .NET. - -## Configuration using environment variables - -Depending on if your proxy server uses HTTP or HTTPS, you will set either the environment variable `HTTP_PROXY` or `HTTPS_PROXY` respectively. The proxy server URL has the form `http[s]://[username:password@]:/` 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/Mac) environments. Setting the appropriate environment variable will then cause the Azure SDK for .NET to use the proxy server at run time. - -### [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:password@10.10.1.10:1180 - -rem Non-authenticated HTTPS server: -set HTTPS_PROXY=http://10.10.1.10:1180 - -rem Authenticated HTTPS server: -set HTTPS_PROXY=http://username:password@10.10.1.10:1180 -``` - -### [bash](#tab/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=http://10.10.1.10:1180 - -# Authenticated HTTPS server: -HTTPS_PROXY=http://username:password@10.10.1.10:1180 -``` - ---- diff --git a/docs/azure/sdk/configure-proxy.md b/docs/azure/sdk/configure-proxy.md new file mode 100644 index 0000000000000..1be1f2946043d --- /dev/null +++ b/docs/azure/sdk/configure-proxy.md @@ -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 object whose `Proxy` property is set. +1. Create a service client options object whose 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@]:/`, 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: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](#tab/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 +``` + +--- diff --git a/docs/azure/sdk/snippets/configure-proxy/Program.cs b/docs/azure/sdk/snippets/configure-proxy/Program.cs new file mode 100644 index 0000000000000..a906663595779 --- /dev/null +++ b/docs/azure/sdk/snippets/configure-proxy/Program.cs @@ -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("")), +}; + +SecretClientOptions options = new() +{ + Transport = new HttpClientTransport(handler), +}; +SecretClient client = new( + new Uri("https://.vault.azure.net/"), + new DefaultAzureCredential(), + options); diff --git a/docs/azure/sdk/snippets/configure-proxy/ProxyServerConfiguration.csproj b/docs/azure/sdk/snippets/configure-proxy/ProxyServerConfiguration.csproj new file mode 100644 index 0000000000000..1993e63491351 --- /dev/null +++ b/docs/azure/sdk/snippets/configure-proxy/ProxyServerConfiguration.csproj @@ -0,0 +1,15 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + +