HttpClient.DefaultProxy environment variable format (#4315)

* HttpClient.DefaultProxy environment variable format

Include additional information about the supported formats for
HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables based on
the handling in [HttpEnvironmentProxy.TryCreate] and
[HttpEnvironmentProxy.GetUriFromString].

The lack of https support (see dotnet/runtime#31113) is specifically
noted since it may catch users by surprise (as it did for me) and is
difficult to debug due to the lack of diagnostic logging.

[HttpEnvironmentProxy.GetUriFromString]: https://github.com/dotnet/runtime/blob/v5.0.0-preview.4.20251.6/src/libraries/System.Net.Http/src/System/Net/Http/SocketsHttpHandler/HttpEnvironmentProxy.cs#L136
[HttpEnvironmentProxy.TryCreate]: https://github.com/dotnet/runtime/blob/v5.0.0-preview.4.20251.6/src/libraries/System.Net.Http/src/System/Net/Http/SocketsHttpHandler/HttpEnvironmentProxy.Unix.cs#L16

Signed-off-by: Kevin Locke <[email protected]>

* Apply suggestions from gewarren

Co-authored-by: Genevieve Warren <[email protected]>

Co-authored-by: Genevieve Warren <[email protected]>

Author: kevinoid

xml/System.Net.Http/HttpClient.xml

@@ -427,11 +427,14 @@ The default instance returned by this property will initialize following a diffe
 * **For Linux:** Reads proxy configuration from environment variables or, in case those are not defined, this property initializes a non-configured instance that bypasses all addresses.
 
 The environment variables used for `DefaultProxy` initialization on Windows and Unix-based platforms are:
-* HTTP_PROXY: the hostname or IP address of the proxy server used on HTTP requests.
-* HTTPS_PROXY: the hostname or IP address of the proxy server used on HTTPS requests.
-* ALL_PROXY: the hostname or IP address of the proxy server used on HTTP and/or HTTPS requests in case HTTP_PROXY and/or HTTPS_PROXY are not defined.
+* HTTP_PROXY: the proxy server used on HTTP requests.
+* HTTPS_PROXY: the proxy server used on HTTPS requests.
+* ALL_PROXY: the proxy server used on HTTP and/or HTTPS requests in case HTTP_PROXY and/or HTTPS_PROXY are not defined.
 * NO_PROXY: a comma-separated list of hostnames that should be excluded from proxying.
 
+On systems where environment variables are case-sensitive, the variable names may be all lowercase or all uppercase.  The lowercase names are checked first.
+
+The proxy server may be a hostname or IP address, optionally followed by a colon and port number, or it may be an http URL, optionally including a username and password for proxy authentication. The URL must be start with `http`, not `https`, and cannot include any text after the hostname, IP, or port.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">The value passed cannot be <see langword="null" />.</exception>