Skip to content

Commit

Permalink
Add XML docs for exceptions that can be thrown by ModuleClient.SendEv…
Browse files Browse the repository at this point in the history 
…entAsync and DeviceClient.SendEventAsync (Azure#2178)

* Add XML docs for exceptions that can be thrown by ModuleClient.SendEventAsync and DeviceClient.SendEventAsync

* Add more XML docs for exceptions for ModuleClient.SendEventAsync and DeviceClient.SendEventAsync

* Update iothub/device/src/DeviceClient.cs

Co-authored-by: David R. Williamson <[email protected]>

* Add using for exceptions

Co-authored-by: David R. Williamson <[email protected]>
  • Loading branch information
@Marusyk
Marusyk and David R. Williamson authored Oct 5, 2021
1 parent 517f443 commit 3ea51d1
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 4 deletions.
37 changes: 36 additions & 1 deletion iothub/device/src/DeviceClient.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Sockets;
using System.Net.WebSockets;
using System.Threading;
using System.Threading.Tasks;
using DotNetty.Transport.Channels;
using Microsoft.Azure.Devices.Client.Exceptions;
using Microsoft.Azure.Devices.Client.Transport;
using Microsoft.Azure.Devices.Shared;

Expand Down Expand Up @@ -475,6 +479,22 @@ public Task SetReceiveMessageHandlerAsync(ReceiveMessageCallback messageHandler,
/// Sends an event to a hub
/// </summary>
/// <param name="message">The message to send. Should be disposed after sending.</param>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="TimeoutException">Thrown if the service does not respond to the request within the timeout specified for the operation.
/// The timeout values are largely transport protocol specific. Check the corresponding transport settings to see if they can be configured.
/// The operation timeout for the client can be set using <see cref="OperationTimeoutInMilliseconds"/>.</exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <returns>The task to await</returns>
public Task SendEventAsync(Message message) => InternalClient.SendEventAsync(message);

Expand All @@ -483,7 +503,22 @@ public Task SetReceiveMessageHandlerAsync(ReceiveMessageCallback messageHandler,
/// </summary>
/// <param name="message">The message to send. Should be disposed after sending.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="OperationCanceledException">Thrown if the service does not respond to the request before the expiration of the passed <see cref="CancellationToken"/>.
/// If a cancellation token is not supplied to the operation call, a cancellation token with an expiration time of 4 minutes is used.
/// </exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <returns>The task to await</returns>
public Task SendEventAsync(Message message, CancellationToken cancellationToken) => InternalClient.SendEventAsync(message, cancellationToken);

Expand Down
72 changes: 69 additions & 3 deletions iothub/device/src/ModuleClient.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,19 @@
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Security;
using System.Net.Sockets;
using System.Net.WebSockets;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using DotNetty.Transport.Channels;
using Microsoft.Azure.Devices.Client.Edge;
using Microsoft.Azure.Devices.Client.Exceptions;
using Microsoft.Azure.Devices.Client.Extensions;
using Microsoft.Azure.Devices.Client.Transport;
using Microsoft.Azure.Devices.Shared;
Expand Down Expand Up @@ -346,6 +351,22 @@ public void SetRetryPolicy(IRetryPolicy retryPolicy)
/// Sends an event to IoT hub
/// </summary>
/// <param name="message">The message.</param>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="TimeoutException">Thrown if the service does not respond to the request within the timeout specified for the operation.
/// The timeout values are largely transport protocol specific. Check the corresponding transport settings to see if they can be configured.
/// The operation timeout for the client can be set using <see cref="OperationTimeoutInMilliseconds"/>.</exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <returns>The message containing the event</returns>
public Task SendEventAsync(Message message) => InternalClient.SendEventAsync(message);

Expand All @@ -354,7 +375,22 @@ public void SetRetryPolicy(IRetryPolicy retryPolicy)
/// </summary>
/// <param name="message">The message.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="OperationCanceledException">Thrown if the service does not respond to the request before the expiration of the passed <see cref="CancellationToken"/>.
/// If a cancellation token is not supplied to the operation call, a cancellation token with an expiration time of 4 minutes is used.
/// </exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <returns>The message containing the event</returns>
public Task SendEventAsync(Message message, CancellationToken cancellationToken) => InternalClient.SendEventAsync(message, cancellationToken);

Expand Down Expand Up @@ -521,7 +557,22 @@ public Task UpdateReportedPropertiesAsync(TwinCollection reportedProperties, Can
/// </summary>
/// <param name="outputName">The output target for sending the given message</param>
/// <param name="message">The message to send</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="TimeoutException">Thrown if the service does not respond to the request within the timeout specified for the operation.
/// The timeout values are largely transport protocol specific. Check the corresponding transport settings to see if they can be configured.
/// The operation timeout for the client can be set using <see cref="OperationTimeoutInMilliseconds"/>.</exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the above list is not exhaustive.
/// </remarks>
/// <returns>The message containing the event</returns>
public Task SendEventAsync(string outputName, Message message) =>
InternalClient.SendEventAsync(outputName, message);
Expand All @@ -532,7 +583,22 @@ public Task SendEventAsync(string outputName, Message message) =>
/// <param name="outputName">The output target for sending the given message</param>
/// <param name="message">The message to send</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="OperationCanceledException">Thrown if the service does not respond to the request before the expiration of the passed <see cref="CancellationToken"/>.
/// If a cancellation token is not supplied to the operation call, a cancellation token with an expiration time of 4 minutes is used.
/// </exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retryable exception. </exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT Hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error details and take steps accordingly.
/// Please note that the above list is not exhaustive.
/// </remarks>
/// <returns>The message containing the event</returns>
public Task SendEventAsync(string outputName, Message message, CancellationToken cancellationToken) =>
InternalClient.SendEventAsync(outputName, message, cancellationToken);
Expand Down

0 comments on commit 3ea51d1

Please sign in to comment.