doc(client, service): Update documents about the Proxy property for various clients

iothub/device/src/AmqpTransportSettings.cs

@@ -156,9 +156,7 @@ public TimeSpan OpenTimeout
         /// </summary>
         public X509Certificate2 ClientCertificate { get; set; }
 
-        /// <summary>
-        /// The proxy
-        /// </summary>
+        /// <inheritdoc/>
         public IWebProxy Proxy { get; set; }
 
         /// <summary>

iothub/device/src/Http1TransportSettings.cs

@@ -45,9 +45,7 @@ public TransportType GetTransportType()
         /// </remarks>
         public TimeSpan DefaultReceiveTimeout => s_defaultOperationTimeout;
 
-        /// <summary>
-        /// Proxy information.
-        /// </summary>
+        /// <inheritdoc/>
         public IWebProxy Proxy { get; set; }
     }
 }

iothub/device/src/ITransportSettings.cs

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using System.Net;
+using Microsoft.Azure.Devices.Shared;
 
 namespace Microsoft.Azure.Devices.Client
 {
@@ -20,5 +22,41 @@ public interface ITransportSettings
         /// The time to wait for a receive operation.
         /// </summary>
         TimeSpan DefaultReceiveTimeout { get; }
+
+        /// <summary>
+        /// The web proxy that will be used to connect to IoT hub using a web socket connection for AMQP, MQTT, or when using the HTTP protocol.
+        /// </summary>
+        /// <value>
+        /// An instance of a class that implements <see cref="IWebProxy"/>.
+        /// </value>
+        /// <remarks>
+        /// This setting will be used when the client attempts to connect over web sockets. For example, if the client attempts to connect to IoT hub using <see cref="TransportType.Amqp"/> or <see cref="TransportType.Mqtt"/> the client will first try over TCP. If that fails, the client will fall back to using web sockets and will use the proxy setting. The setting will also be used when <see cref="TransportType.Amqp_WebSocket_Only"/>, <see cref="TransportType.Mqtt_WebSocket_Only"/>, or <see cref="TransportType.Http1"/> is specified. 
+        /// </remarks>
+        /// <example>
+        /// To set a proxy you must instantiate an instance of the <see cref="WebProxy"/> class--or any class that derives from <see cref="IWebProxy"/>. The snippet below shows a method that returns a device using a proxy that connects to localhost on port 8888.
+        /// <code>
+        /// static DeviceClient GetClientWithProxy()
+        /// {
+        ///     try
+        ///     {
+        ///         var proxyHost = "localhost";
+        ///         var proxyPort = 8888;
+        ///         // Specify the WebProxy to be used for the web socket connection
+        ///         var transportSettings = new AmqpTransportSettings(Microsoft.Azure.Devices.Client.TransportType.Amqp_WebSocket_Only)
+        ///         {
+        ///             Proxy = new WebProxy(proxyHost, proxyPort)
+        ///         };
+        ///         var deviceClient = DeviceClient.CreateFromConnectionString("a connection string", new ITransportSettings[] { transportSettings });
+        ///         return deviceClient;
+        ///     }
+        ///     catch (Exception)
+        ///     {
+        ///         Console.WriteLine("Error creating client.");
+        ///         throw;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
+        IWebProxy Proxy { get; set; }
     }
 }

iothub/device/src/Transport/Mqtt/MqttTransportSettings.cs

@@ -232,9 +232,7 @@ public bool CertificateRevocationCheck
         /// </summary>
         public X509Certificate ClientCertificate { get; set; }
 
-        /// <summary>
-        /// The proxy settings to be used when communicating with IoT Hub.
-        /// </summary>
+        /// <inheritdoc/>
         public IWebProxy Proxy { get; set; }
 
         /// <summary>

iothub/service/src/HttpTransportSettings.cs

@@ -20,12 +20,39 @@ public HttpTransportSettings()
         }
 
         /// <summary>
-        /// Proxy information.
+        /// The web proxy that will be used to connect to IoT hub when using the HTTP protocol.
         /// </summary>
+        /// <value>
+        /// An instance of a class that implements <see cref="IWebProxy"/>.
+        /// </value>
         /// <remarks>
-        /// This is used when a device is on a network that doesn't have direct internet access and needs to access it via a proxy,
-        /// especially when MQTT and AMQP ports are disallowed to the internet.
+        /// The <see cref="HttpTransportSettings"/> class is only used for the <see cref="JobClient"/> or the <see cref="RegistryManager"/>; so the proxy set here will only be valid for those clients.
         /// </remarks>
+        /// <example>
+        /// To set a proxy you must instantiate an instance of the <see cref="WebProxy"/> class--or any class that derives from <see cref="IWebProxy"/>. The snippet below shows a method that returns a device using a proxy that connects to localhost on port 8888.
+        /// <code>
+        /// static JobClient GetJobClient()
+        /// {
+        ///     try
+        ///     {
+        ///         var proxyHost = "localhost";
+        ///         var proxyPort = 8888;
+        ///         var transportSettings = new HttpTransportSettings
+        ///         {
+        ///             Proxy = new WebProxy(proxyHost, proxyPort)
+        ///         };
+        ///         // Specify the WebProxy to be used for the HTTP connection
+        ///         var jobClient = JobClient.CreateFromConnectionString("a connection string", transportSettings);
+        ///         return jobClient;
+        ///     }
+        ///     catch (Exception)
+        ///     {
+        ///         Console.WriteLine("Error creating client.");
+        ///         throw;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         public IWebProxy Proxy { get; set; }
 
         /// <summary>

iothub/service/src/ServiceClientTransportSettings.cs

@@ -21,13 +21,78 @@ public ServiceClientTransportSettings()
         }
 
         /// <summary>
-        /// The proxy settings to be used on the AMQP client.
+        /// The web proxy that will be used to connect to IoT hub when using the AMQP over web sockets.
         /// </summary>
+        /// <value>
+        /// An instance of a class that implements <see cref="IWebProxy"/>.
+        /// </value>
+        /// <remarks>
+        /// This setting will be used when the client attempts to connect over web sockets. For example, if the client attempts to connect to IoT hub using <see cref="TransportType.Amqp"/> the client will first try over TCP. If that fails, the client will fall back to using web sockets and will use the proxy setting. This setting is to be used in conjunction with the <see cref="HttpProxy"/> property.
+        /// </remarks>
+        /// <example>
+        /// To set a proxy you must instantiate an instance of the <see cref="WebProxy"/> class--or any class that derives from <see cref="IWebProxy"/>. The snippet below shows a method that returns a device using a proxy that connects to localhost on port 8888.
+        /// <code>
+        /// static ServiceClient GetServiceClient()
+        /// {
+        ///     try
+        ///     {
+        ///         var proxyHost = "localhost";
+        ///         var proxyPort = 8888;
+        ///         var proxy = new WebProxy(proxyHost, proxyPort);
+        ///         var transportSettings = new ServiceClientTransportSettings
+        ///         {
+        ///             AmqpProxy = proxy,
+        ///             HttpProxy = proxy
+        ///         };
+        ///         var serviceClient = ServiceClient.CreateFromConnectionString("a connection string", Microsoft.Azure.Devices.TransportType.Amqp_WebSocket_Only, transportSettings );
+        ///         return serviceClient;
+        ///     }
+        ///     catch (Exception)
+        ///     {
+        ///         Console.WriteLine("Error creating client.");
+        ///         throw;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         public IWebProxy AmqpProxy { get; set; }
 
         /// <summary>
-        /// The proxy settings to be used on the HTTP client.
+        /// The web proxy that will be used to connect to IoT hub when operations must execute over HTTP.
         /// </summary>
+        /// <value>
+        /// An instance of a class that implements <see cref="IWebProxy"/>.
+        /// </value>
+        /// <remarks>
+        /// Methods such as <see cref="ServiceClient.GetServiceStatisticsAsync(System.Threading.CancellationToken)"/> are executed over HTTP and not AMQP. This setting will ensure those methods are executed over the specified proxy. This setting is to be used in conjunction with the <see cref="AmqpProxy"/> property.
+        /// </remarks>
+        /// <example>
+        /// To set a proxy you must instantiate an instance of the <see cref="WebProxy"/> class--or any class that derives from <see cref="IWebProxy"/>. The snippet below shows a method that returns a device using a proxy that connects to localhost on port 8888.
+        /// <code>
+        /// static ServiceClient GetServiceClient()
+        /// {
+        ///     try
+        ///     {
+        ///         var proxyHost = "localhost";
+        ///         var proxyPort = 8888;
+        ///         var proxy = new WebProxy(proxyHost, proxyPort);
+        ///         var transportSettings = new ServiceClientTransportSettings
+        ///         {
+        ///             AmqpProxy = proxy,
+        ///             HttpProxy = proxy
+        ///         };
+        ///         // Specify the WebProxy to be used for the web socket connection
+        ///         var serviceClient = ServiceClient.CreateFromConnectionString("a connection string", Microsoft.Azure.Devices.TransportType.Amqp_WebSocket_Only, transportSettings );
+        ///         return serviceClient;
+        ///     }
+        ///     catch (Exception)
+        ///     {
+        ///         Console.WriteLine("Error creating client.");
+        ///         throw;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         public IWebProxy HttpProxy { get; set; }
 
         /// <summary>