Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add code examples for public APIs in IotHubDeviceClient, IotHubModuleClient, IotHubBaseClient and retry policies #3308

Merged
merged 6 commits into from
Apr 28, 2023
Merged

Add code examples for public APIs in IotHubDeviceClient, IotHubModuleClient, IotHubBaseClient and retry policies #3308

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d864cd3
Add code examples for public APIs in IotHubDeviceClient, IotHubModule…
brycewang-microsoft Apr 27, 2023
6d9efbc
fix broken link in migration guide
brycewang-microsoft Apr 27, 2023
4956469
add code examples for device retry policies
brycewang-microsoft Apr 27, 2023
7acd567
partial pr comments
brycewang-microsoft Apr 27, 2023
9d6416d
pr comments
brycewang-microsoft Apr 28, 2023
1d03d15
fixup
brycewang-microsoft Apr 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion SDK v2 migration guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Provided here are lists of the notable changes as well as a mapping from v1 to v
- [Why the v1 SDK is being replaced](#why-the-v1-sdk-is-being-replaced)
- [What will happen to the v1 SDK](#What-will-happen-to-the-v1-sdk)
- [Migration guide](#migration-guide)
- [IoT hub device client](#iot-hub-device-client)
- [IoT hub device clients](#iot-hub-device-clients)
- [IoT hub service client](#iot-hub-service-client)
- [Device Provisioning Service (DPS) device client](#dps-device-client)
- [DPS service client](#dps-service-client)
Expand Down
78 changes: 76 additions & 2 deletions iothub/device/src/IotHubBaseClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,11 @@ internal IotHubBaseClient(
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.OpenAsync(cancellationToken);
/// </code>
/// </example>
public async Task OpenAsync(CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
Expand Down Expand Up @@ -156,6 +161,11 @@ public async Task OpenAsync(CancellationToken cancellationToken = default)
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.SendTelemetryAsync(new TelemetryMessage(payload), cancellationToken);
/// </code>
/// </example>
public async Task SendTelemetryAsync(TelemetryMessage message, CancellationToken cancellationToken = default)
{
Argument.AssertNotNull(message, nameof(message));
Expand Down Expand Up @@ -208,6 +218,15 @@ public async Task SendTelemetryAsync(TelemetryMessage message, CancellationToken
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// var client = new IotHubDeviceClient(
/// connectionString,
/// new IotHubClientOptions(new IotHubClientAmqpSettings())); // This operation only works over AMQP
///
/// await client.SendTelemetryAsync(new List<TelemetryMessage/> { message1, message2 }, cancellationToken);
/// </code>
/// </example>
public async Task SendTelemetryAsync(IEnumerable<TelemetryMessage> messages, CancellationToken cancellationToken = default)
{
Argument.AssertNotNullOrEmpty(messages, nameof(messages));
Expand Down Expand Up @@ -251,6 +270,18 @@ public async Task SendTelemetryAsync(IEnumerable<TelemetryMessage> messages, Can
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.SetIncomingMessageCallbackAsync(OnC2dMessageReceivedAsync);
/// //...
///
/// Task<MessageAcknowledgement/> OnC2dMessageReceivedAsync(IncomingMessage receivedMessage)
/// {
/// // Add message handling logic as needed
/// return Task.FromResult(MessageAcknowledgement.Complete);
/// }
/// </code>
/// </example>
public async Task SetIncomingMessageCallbackAsync(
Func<IncomingMessage, Task<MessageAcknowledgement>> messageCallback,
CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -308,6 +339,18 @@ public async Task SetIncomingMessageCallbackAsync(
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.SetDirectMethodCallbackAsync(OnDirectMethodCalledAsync, cancellationToken);
/// //...
///
/// Task<DirectMethodResponse/> OnDirectMethodCalledAsync(DirectMethodRequest directMethodRequest)
/// {
/// // Add method request handling logic as needed
/// return new DirectMethodResponse(200);
/// }
/// </code>
/// </example>
public async Task SetDirectMethodCallbackAsync(
Func<DirectMethodRequest, Task<DirectMethodResponse>> directMethodCallback,
CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -351,11 +394,16 @@ public async Task SetDirectMethodCallbackAsync(
/// </para>
/// </remarks>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <returns>The twin object for the current client.</returns>
/// <exception cref="InvalidOperationException">The client instance is not already open.</exception>
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <returns>The twin object for the current client.</returns>
/// <example>
/// <code language="csharp">
/// TwinProperties twin = await client.GetTwinPropertiesAsync(cancellationToken);
/// </code>
/// </example>
public async Task<TwinProperties> GetTwinPropertiesAsync(CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
Expand All @@ -371,12 +419,22 @@ public async Task<TwinProperties> GetTwinPropertiesAsync(CancellationToken cance
/// </remarks>
/// <param name="reportedProperties">Reported properties to push</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <returns>The new version of the updated twin if the update was successful.</returns>
/// <exception cref="ArgumentNullException"><paramref name="reportedProperties"/> is null.</exception>
/// <exception cref="InvalidOperationException">The client instance is not already open.</exception>
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <returns>The new version of the updated twin if the update was successful.</returns>
/// <example>
/// <code language="csharp">
/// long newVersion = await client.UpdateReportedPropertiesAsync(
/// new ReportedProperties
/// {
/// [key1] = value1,
/// [key2] = value2,
/// });
/// </code>
/// </example>
public async Task<long> UpdateReportedPropertiesAsync(ReportedProperties reportedProperties, CancellationToken cancellationToken = default)
{
Argument.AssertNotNull(reportedProperties, nameof(reportedProperties));
Expand Down Expand Up @@ -408,6 +466,17 @@ public async Task<long> UpdateReportedPropertiesAsync(ReportedProperties reporte
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync);
/// //...
///
/// Task OnDesiredPropertyChangedAsync(DesiredProperties desiredProperties)
/// {
/// // Add received desired properties handling logic as needed
/// }
/// </code>
/// </example>
public async Task SetDesiredPropertyUpdateCallbackAsync(
Func<DesiredProperties, Task> callback,
CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -453,6 +522,11 @@ public async Task SetDesiredPropertyUpdateCallbackAsync(
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.CloseAsync(cancellationToken);
/// </code>
/// </example>
public async Task CloseAsync(CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
Expand Down
33 changes: 32 additions & 1 deletion iothub/device/src/IotHubDeviceClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,13 @@ public class IotHubDeviceClient : IotHubBaseClient
/// or the IoT hub host name or device Id in the connection string are an empty string or consist only of white-space characters.</exception>
/// <exception cref="ArgumentException">Neither shared access key nor shared access signature were presented for authentication.</exception>
/// <exception cref="InvalidOperationException">A module Id was specified in the connection string. <see cref="IotHubModuleClient"/> should be used for modules.</exception>
/// <example>
/// <code language="csharp">
/// await using var client = new IotHubDeviceClient(
/// connectionString,
/// new IotHubClientOptions(new IotHubClientMqttSettings(IotHubClientTransportProtocol.WebSocket)));
/// </code>
/// </example>
public IotHubDeviceClient(string connectionString, IotHubClientOptions options = default)
: this(new IotHubConnectionCredentials(connectionString), options)
{
Expand All @@ -55,6 +62,14 @@ public IotHubDeviceClient(string connectionString, IotHubClientOptions options =
/// <exception cref="ArgumentException"><see cref="ClientAuthenticationWithX509Certificate.CertificateChain"/> is used over a protocol other than MQTT over TCP or AMQP over TCP></exception>
/// <exception cref="IotHubClientException"><see cref="ClientAuthenticationWithX509Certificate.CertificateChain"/> could not be installed.</exception>
/// <exception cref="InvalidOperationException">A module Id was specified in the provided <paramref name="authenticationMethod"/>. <see cref="IotHubModuleClient"/> should be used for modules.</exception>
/// <example>
/// <code language="csharp">
/// await using var client = new IotHubDeviceClient(
/// hostName,
/// new ClientAuthenticationWithSharedAccessKeyRefresh(sharedAccessKey, deviceId),
/// new IotHubClientOptions(new IotHubClientMqttSettings(IotHubClientTransportProtocol.WebSocket)));
/// </code>
/// </example>
public IotHubDeviceClient(string hostName, IAuthenticationMethod authenticationMethod, IotHubClientOptions options = default)
: this(new IotHubConnectionCredentials(authenticationMethod, hostName, options?.GatewayHostName), options)
{
Expand Down Expand Up @@ -87,7 +102,7 @@ private IotHubDeviceClient(IotHubConnectionCredentials iotHubConnectionCredentia
}

/// <summary>
/// Get a file upload SAS URI which the Azure Storage SDK can use to upload a file to blob for this device
/// Get a file upload SAS URI which the Azure Storage SDK can use to upload a file to blob for this device.
/// </summary>
/// <remarks>
/// See <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-file-upload#initialize-a-file-upload">this documentation for more details</see>.
Expand All @@ -100,6 +115,11 @@ private IotHubDeviceClient(IotHubConnectionCredentials iotHubConnectionCredentia
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// FileUploadSasUriResponse sasUri = await client.GetFileUploadSasUriAsync(new FileUploadSasUriRequest(fileName), cancellationToken);
/// </code>
/// </example>
public Task<FileUploadSasUriResponse> GetFileUploadSasUriAsync(
FileUploadSasUriRequest request,
CancellationToken cancellationToken = default)
Expand All @@ -121,6 +141,17 @@ public Task<FileUploadSasUriResponse> GetFileUploadSasUriAsync(
/// <exception cref="OperationCanceledException">The operation has been canceled.</exception>
/// <exception cref="IotHubClientException">An error occured when communicating with IoT hub service.</exception>
/// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
/// <example>
/// <code language="csharp">
/// await client.CompleteFileUploadAsync(
/// new FileUploadCompletionNotification(correlationId: correlationId, isSuccess: true)
/// {
/// StatusCode = 200,
/// StatusDescription = "Success",
/// },
/// cancellationToken);
/// </code>
/// </example>
public Task CompleteFileUploadAsync(FileUploadCompletionNotification notification, CancellationToken cancellationToken = default)
{
Argument.AssertNotNull(notification, nameof(notification));
Expand Down
Loading