From a6548fb8316a45e9525895a573b8f0f31f702364 Mon Sep 17 00:00:00 2001 From: David Cantu Date: Tue, 9 Jul 2019 09:47:03 -0700 Subject: [PATCH 1/3] Added documentation for System.Net.Http properties --- xml/System.Net.Http/HttpClient.xml | 54 ++++++++++++++++++--- xml/System.Net.Http/HttpResponseMessage.xml | 18 +++++-- 2 files changed, 62 insertions(+), 10 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index cafa84df4a8..1c9fe68198f 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -363,9 +363,36 @@ public class GoodController : ApiController System.Net.IWebProxy - To be added. - To be added. - To be added. + Gets or sets the global Http proxy. + A proxy used by every call that instantiates a . + +  property gets or sets the global proxy. The  property determines the default proxy that all  instances use if no proxy is set explicitly in the  passed through its constructor. + +If the  property is overridden, all subsequent instances of the  class that does not define its own Proxy in will be using the new defined Proxy in . + +The property reads proxy settings from your system configuration and follows a certain behavior depending on your platform: + +* **For Windows:** Reads proxy configuration from Environment Variables, If there are not defined, the current user's proxy settings are used. + +* **For OSX:** Reads proxy configuration from Environment Variables, If they are not defined, the System Proxy Information settings are used. + +* **For Linux:** Reads proxy configuration from Environment Variables, If they are not defined, no proxy is defined. + +The Environment Variables used for the DefaultProxy initialization are: +* HTTP_PROXY +* HTTPS_PROXY +* ALL_PROXY +* NO_PROXY + +The name of Environment Variables remain constant across Windows, OSX, and Linux platforms. + ]]> + + + The value passed cannot be . + @@ -424,10 +451,23 @@ public class GoodController : ApiController System.Version - To be added. - To be added. - To be added. - + Gets or sets the default version used on subsequent requests made by this instance. + The which is going to be set on instances created by this instance. + + is by default. + +The property would be set as the on any the instance creates, in example, as part of a call to , , , etc. + +The property can be overriden as long as the instance has not started any request. + ]]> + + Cannot set a value to . + The instance has already started one or more requests. + instance has already been disposed. + diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml index cfe422c318c..fdad6b073c1 100644 --- a/xml/System.Net.Http/HttpResponseMessage.xml +++ b/xml/System.Net.Http/HttpResponseMessage.xml @@ -484,9 +484,21 @@ System.Net.Http.Headers.HttpResponseHeaders - To be added. - To be added. - To be added. + Gets the collection of trailing headers included in a HTTP response. + The collection of trailing headers in the HTTP response. + + property will return an empty HttpResponseHeaders instance if its accessed and the response content has not been read completely (See example below). + +For further information on trailing headers see [RFC 7230 - 4.1.2. Chunked Trailer Part](https://tools.ietf.org/html/rfc7230#section-4.1.2). + + ]]> + + PROTOCOL_ERROR: The HTTP/2 response contains pseudo-headers in the Trailing Headers Frame. From 8269cfcd9911c018b18a299211888c910591929b Mon Sep 17 00:00:00 2001 From: David Cantu Date: Tue, 23 Jul 2019 09:24:04 -0700 Subject: [PATCH 2/3] Addressed PR comments. Reworded DefaultProxy platform-specific configuration. --- xml/System.Net.Http/HttpClient.xml | 42 ++++++++++----------- xml/System.Net.Http/HttpResponseMessage.xml | 6 +-- 2 files changed, 22 insertions(+), 26 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 1c9fe68198f..8818ba92524 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -364,30 +364,26 @@ public class GoodController : ApiController Gets or sets the global Http proxy. - A proxy used by every call that instantiates a . + A proxy used by every call that instantiates a .  property gets or sets the global proxy. The  property determines the default proxy that all  instances use if no proxy is set explicitly in the  passed through its constructor. - -If the  property is overridden, all subsequent instances of the  class that does not define its own Proxy in will be using the new defined Proxy in . - -The property reads proxy settings from your system configuration and follows a certain behavior depending on your platform: +## Remarks +This static property determines the default proxy that all  instances use if no proxy is set explicitly in the  passed through its constructor. -* **For Windows:** Reads proxy configuration from Environment Variables, If there are not defined, the current user's proxy settings are used. +The default instance returned by this property will initialize following a different set of rules depending on your platform: +* **For Windows:** Reads proxy configuration from environment variables, if those are not defined, the user's proxy settings. -* **For OSX:** Reads proxy configuration from Environment Variables, If they are not defined, the System Proxy Information settings are used. +* **For OSX:** Reads proxy configuration from environment variables, if those are not defined, the system's proxy settings. -* **For Linux:** Reads proxy configuration from Environment Variables, If they are not defined, no proxy is defined. +* **For Unix:** Reads proxy configuration from environment variables, in case those are not defined, this property initializes a non-configured instance that bypasses all addresses. -The Environment Variables used for the DefaultProxy initialization are: -* HTTP_PROXY -* HTTPS_PROXY -* ALL_PROXY -* NO_PROXY +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. +* NO_PROXY: a comma-separated list of hostnames that should be excluded from proxying. -The name of Environment Variables remain constant across Windows, OSX, and Linux platforms. ]]> @@ -451,22 +447,22 @@ The name of Environment Variables remain constant across Windows, OSX, and Linux System.Version - Gets or sets the default version used on subsequent requests made by this instance. - The which is going to be set on instances created by this instance. + Gets or sets the default HTTP version used on subsequent requests made by this instance. + The default version to use for any requests made with this instance. is by default. +`DefaultRequestVersion` is by default. -The property would be set as the on any the instance creates, in example, as part of a call to , , , etc. +The `DefaultRequestVersion` property specifies the default HTTP version to use for any requests sent using this instance, such as calls to , , or . -The property can be overriden as long as the instance has not started any request. +The `DefaultRequestVersion` property can be changed as long as the instance has not started any request. ]]> - Cannot set a value to . + In a set operation, is . The instance has already started one or more requests. - instance has already been disposed. + The instance has already been disposed. diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml index fdad6b073c1..226d5264493 100644 --- a/xml/System.Net.Http/HttpResponseMessage.xml +++ b/xml/System.Net.Http/HttpResponseMessage.xml @@ -484,7 +484,7 @@ System.Net.Http.Headers.HttpResponseHeaders - Gets the collection of trailing headers included in a HTTP response. + Gets the collection of trailing headers included in an HTTP response. The collection of trailing headers in the HTTP response. property will return an empty HttpResponseHeaders instance if its accessed and the response content has not been read completely (See example below). +Since trailing headers are send as an HTTP header appended at the end of the response message, the `TrailingHeaders` property returns an empty instance if it is accessed and the response content has not been read completely. -For further information on trailing headers see [RFC 7230 - 4.1.2. Chunked Trailer Part](https://tools.ietf.org/html/rfc7230#section-4.1.2). +For additional information on trailing headers, see [RFC 7230 - 4.1.2. Chunked Trailer Part](https://tools.ietf.org/html/rfc7230#section-4.1.2). ]]> From c913626cd7225c5f6861ff9b86feb531bebbba9c Mon Sep 17 00:00:00 2001 From: David Cantu Date: Thu, 25 Jul 2019 09:48:11 -0700 Subject: [PATCH 3/3] Apply suggestions from code review * Applying lexical suggestions. * replaced OSX for macOS and Unix for Linux. Co-Authored-By: Ron Petrusha --- xml/System.Net.Http/HttpClient.xml | 8 ++++---- xml/System.Net.Http/HttpResponseMessage.xml | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 8818ba92524..45d0985c067 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -372,11 +372,11 @@ public class GoodController : ApiController This static property determines the default proxy that all  instances use if no proxy is set explicitly in the  passed through its constructor. The default instance returned by this property will initialize following a different set of rules depending on your platform: -* **For Windows:** Reads proxy configuration from environment variables, if those are not defined, the user's proxy settings. +* **For Windows:** Reads proxy configuration from environment variables or, if those are not defined, from the user's proxy settings. -* **For OSX:** Reads proxy configuration from environment variables, if those are not defined, the system's proxy settings. +* **For macOS:** Reads proxy configuration from environment variables or, if those are not defined, from the system's proxy settings. -* **For Unix:** Reads proxy configuration from environment variables, in case those are not defined, this property initializes a non-configured instance that bypasses all addresses. +* **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. @@ -2275,4 +2275,4 @@ httpClient.Timeout = TimeSpan.FromMinutes(10); - \ No newline at end of file + diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml index 226d5264493..b0f4bca34be 100644 --- a/xml/System.Net.Http/HttpResponseMessage.xml +++ b/xml/System.Net.Http/HttpResponseMessage.xml @@ -492,7 +492,7 @@ ## Remarks Forbidden headers will be ignored. -Since trailing headers are send as an HTTP header appended at the end of the response message, the `TrailingHeaders` property returns an empty instance if it is accessed and the response content has not been read completely. +Since trailing headers are sent as an HTTP header appended at the end of the response message, the `TrailingHeaders` property returns an empty instance if it is accessed and the response content has not been read completely. For additional information on trailing headers, see [RFC 7230 - 4.1.2. Chunked Trailer Part](https://tools.ietf.org/html/rfc7230#section-4.1.2). @@ -532,4 +532,4 @@ For additional information on trailing headers, see [RFC 7230 - 4.1.2. Chunked T - \ No newline at end of file +