Add more doc comments for handling user-supplied callbacks for cloud-to-device communication

e2e/test/helpers/TestDeviceCallbackHandler.cs

@@ -70,7 +70,7 @@ await _deviceClient.SetDirectMethodCallbackAsync(
 
                         _methodExceptionDispatch = ExceptionDispatchInfo.Capture(ex);
 
-                        var response = new Client.DirectMethodResponse(500);
+                        var response = new DirectMethodResponse(500);
 
                         return Task.FromResult(response);
                     }

e2e/test/helpers/templates/FaultInjection.cs

@@ -4,7 +4,6 @@
 using System;
 using System.Diagnostics;
 using System.Globalization;
-using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;

iothub/device/src/IotHubBaseClient.cs

@@ -79,6 +79,10 @@ internal IotHubBaseClient(
         /// <summary>
         /// The callback to be executed each time connection status change notification is received.
         /// </summary>
+        /// <remarks>
+        /// All of requests will be processed as they arrive. If you put async code within this
+        /// callback, you'll need to handle exceptions that could originate in there.
+        /// </remarks>
         /// <example>
         /// deviceClient.ConnectionStatusChangeCallback = OnConnectionStatusChanged;
         /// //...
@@ -193,6 +197,8 @@ public async Task SendTelemetryBatchAsync(IEnumerable<TelemetryMessage> messages
         /// <remarks>
         /// Calling this API more than once will result in the callback set last overwriting any previously set callback.
         /// A method callback can be unset by setting <paramref name="messageCallback"/> to null.
+        /// This user-supplied callback is awaited by the SDK. All of requests will be processed as they arrive.
+        /// Exceptions thrown within the callback will be caught and logged by the SDK internally.
         /// </remarks>
         /// <param name="messageCallback">The callback to be invoked when a cloud-to-device message is received by the client.</param>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
@@ -244,6 +250,8 @@ public async Task SetIncomingMessageCallbackAsync(
         /// <remarks>
         /// Calling this API more than once will result in the callback set last overwriting any previously set callback.
         /// A method callback can be unset by setting <paramref name="directMethodCallback"/> to null.
+        /// This user-supplied callback is awaited by the SDK. All of requests will be processed as they arrive.
+        /// Exceptions thrown within the callback will be caught and logged by the SDK internally.
         /// </remarks>
         /// <param name="directMethodCallback">The callback to be invoked when any method is invoked by the cloud service.</param>
         /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
@@ -323,6 +331,8 @@ public async Task<long> UpdateReportedPropertiesAsync(ReportedProperties reporte
         /// </summary>
         /// <remarks>
         /// Calling this API more than once will result in the callback set last overwriting any previously set callback.
+        /// This user-supplied callback is "fire-and-forget" and the SDK doesn't wait on it. All of requests will be processed as they arrive.
+        /// The users are responsible to handle exceptions within their callback implementation.
         /// A method callback can be unset by setting <paramref name="callback"/> to null.
         ///  <para>
         /// This has the side-effect of subscribing to the PATCH topic on the service.
@@ -579,6 +589,13 @@ internal async Task<MessageAcknowledgement> OnMessageReceivedAsync(IncomingMessa
 
                 return MessageAcknowledgement.Abandon;
             }
+            catch (Exception ex)
+            {
+                if (Logging.IsEnabled)
+                    Logging.Error(this, $"Abandoning message with message Id: {message.MessageId} because user code threw exception: {ex}.", nameof(OnMessageReceivedAsync));
+
+                return MessageAcknowledgement.Abandon;
+            }
             finally
             {
                 if (Logging.IsEnabled)