Add more doc comments for handling user-supplied callbacks for cloud-to-device communication #2939
Conversation
brycewang-microsoft
requested review from
drwill-ms,
timtay-microsoft,
abhipsaMisra,
andyk-ms,
tmahmood-microsoft,
ngastelum-ms and
patilsnr
as code owners
| @@ -79,6 +79,11 @@ public abstract class IotHubBaseClient : IDisposable | |||
| /// <summary> | |||
| /// The callback to be executed each time connection status change notification is received. | |||
| /// </summary> | |||
| /// <remarks> | |||
| /// This user-supplied callback is "fire-and-forget" and the SDK doesn't wait on it. | |||
There was a problem hiding this comment.
Do we have reference or document to point out what are the exceptions the user can expect?
What about updating the example with 'try/catch' to explicitly remind the user about handling exceptions?
There was a problem hiding this comment.
We call the user's callback, therefore we can't throw exceptions that would impact them here. However, if they throw an exception, we need to handle it so as to not crash the process. We're just fixing and documenting that behavior.
There was a problem hiding this comment.
This specific callback doesn't return anything (Action<ConnectionStatusInfo>), so instead of calling this fire-and-forget (which would mean that it returns a task but we don't await on it) why don't we call out that only if you put async code within this callback, you'll need to handle exceptions that could originate in there?
Co-authored-by: David R. Williamson <drwill@microsoft.com>
|
/azp run |
|
Azure Pipelines successfully started running 1 pipeline(s). |
|
/azp run |
|
Azure Pipelines successfully started running 1 pipeline(s). |
Also add internal exception handling for those user-supplied callbacks.
I don't feel confident about good places for putting these doc comments to share with users, so open to any suggestions.