diff --git a/iothub/device/src/DeviceClient.ConventionBasedOperations.cs b/iothub/device/src/DeviceClient.ConventionBasedOperations.cs index 9331bb8f26..dbfb6d8341 100644 --- a/iothub/device/src/DeviceClient.ConventionBasedOperations.cs +++ b/iothub/device/src/DeviceClient.ConventionBasedOperations.cs @@ -16,7 +16,7 @@ namespace Microsoft.Azure.Devices.Client public partial class DeviceClient : IDisposable { /// - /// The that the client uses for convention-based operations. + /// The payload convention implementation that the client uses for convention-based operations. /// public PayloadConvention PayloadConvention => InternalClient.PayloadConvention; @@ -25,7 +25,7 @@ public partial class DeviceClient : IDisposable /// /// /// Use the constructor to pass in the optional component name - /// that the telemetry message is from. + /// that the telemetry message belongs to. /// /// The telemetry message. /// A cancellation token to cancel the operation. @@ -33,7 +33,7 @@ public Task SendTelemetryAsync(TelemetryMessage telemetryMessage, CancellationTo => InternalClient.SendTelemetryAsync(telemetryMessage, cancellationToken); /// - /// Set the global command callback handler. + /// Set the command callback handler. /// /// A method implementation that will handle the incoming command. /// Generic parameter to be interpreted by the client code. @@ -47,7 +47,7 @@ public Task SubscribeToCommandsAsync( /// Retrieve the client properties. /// /// A cancellation token to cancel the operation. - /// The device properties. + /// The client properties. public Task GetClientPropertiesAsync(CancellationToken cancellationToken = default) => InternalClient.GetClientTwinPropertiesAsync(cancellationToken); @@ -58,16 +58,21 @@ public Task GetClientPropertiesAsync(CancellationToken cancell /// Reported properties to push. /// A cancellation token to cancel the operation. /// The response of the update operation. - public Task UpdateClientPropertiesAsync(ClientPropertyCollection propertyCollection, CancellationToken cancellationToken = default) + public Task UpdateClientPropertiesAsync( + ClientPropertyCollection propertyCollection, + CancellationToken cancellationToken = default) => InternalClient.UpdateClientPropertiesAsync(propertyCollection, cancellationToken); /// - /// Sets the global listener for writable property update events. + /// Sets the listener for writable property update events. /// - /// The global call back to handle all writable property updates. + /// The callback to handle all writable property updates. /// Generic parameter to be interpreted by the client code. /// A cancellation token to cancel the operation. - public Task SubscribeToWritablePropertyUpdateRequestsAsync(Func callback, object userContext, CancellationToken cancellationToken = default) + public Task SubscribeToWritablePropertyUpdateRequestsAsync( + Func callback, + object userContext, + CancellationToken cancellationToken = default) => InternalClient.SubscribeToWritablePropertyUpdateRequestsAsync(callback, userContext, cancellationToken); } } diff --git a/iothub/device/src/PayloadCollection.cs b/iothub/device/src/PayloadCollection.cs index d4dcbc2295..027bf5e7bc 100644 --- a/iothub/device/src/PayloadCollection.cs +++ b/iothub/device/src/PayloadCollection.cs @@ -28,18 +28,16 @@ public abstract class PayloadCollection : IEnumerable - /// Get the value at the specified key. + /// Gets the value with the specified key. /// /// /// This accessor is best used to access and cast to simple types. /// It is recommended to use to deserialize to a complex type. /// - /// /// For setting component-level property values see - /// and instead. - /// These convenience methods ensure that component-level properties include the component identifier markers { "__t": "c" }. + /// and instead + /// as these convenience methods ensure that component-level properties include the component identifier markers: { "__t": "c" }. /// For more information see . - /// /// /// /// Key of value. @@ -73,8 +71,8 @@ public virtual void Add(string key, object value) /// For property operations see /// and instead. /// - /// The name of the telemetry. - /// The value of the telemetry. + /// The name of the key to be added to the collection. + /// The value to be added to the collection. /// is null. public virtual void AddOrUpdate(string key, object value) { @@ -95,10 +93,10 @@ public virtual byte[] GetPayloadObjectBytes() } /// - /// Determines whether the specified property is present. + /// Determines whether the specified key is present. /// /// The key in the collection to locate. - /// true if the specified property is present; otherwise, false. + /// true if the specified property is present, otherwise false. public bool Contains(string key) { return Collection.ContainsKey(key); @@ -114,6 +112,8 @@ public bool Contains(string key) /// True if a value of type T with the specified key was found; otherwise, it returns false. public bool TryGetValue(string key, out T value) { + value = default; + if (Logging.IsEnabled && Convention == null) { Logging.Info(this, $"The convention for this collection is not set; this typically means this collection was not created by the client. " + @@ -123,7 +123,6 @@ public bool TryGetValue(string key, out T value) // If the key is null, empty or whitespace, then return false with the default value of the type passed in. if (string.IsNullOrWhiteSpace(key)) { - value = default; return false; } @@ -145,7 +144,6 @@ public bool TryGetValue(string key, out T value) // If the value associated with the key is null, then return true with the default value of the type passed in. if (retrievedPropertyValue == null) { - value = default; return true; } @@ -175,12 +173,14 @@ public bool TryGetValue(string key, out T value) { // Case 3a: // Check if the retrieved value is a writable property update acknowledgment - var newtonsoftWritablePropertyResponse = Convention.PayloadSerializer.ConvertFromObject(retrievedPropertyValue); + var newtonsoftWritablePropertyResponse = Convention.PayloadSerializer + .ConvertFromObject(retrievedPropertyValue); if (typeof(IWritablePropertyResponse).IsAssignableFrom(typeof(T))) { - // If T is IWritablePropertyResponse the property value should be of type IWritablePropertyResponse as defined in the PayloadSerializer. - // We'll convert the json object to NewtonsoftJsonWritablePropertyResponse and then convert it to the appropriate IWritablePropertyResponse object. + // If T is IWritablePropertyResponse the property value should be of type IWritablePropertyResponse as + // defined in the PayloadSerializer. We'll convert the json object to NewtonsoftJsonWritablePropertyResponse + // and then convert it to the appropriate IWritablePropertyResponse object. value = (T)Convention.PayloadSerializer.CreateWritablePropertyResponse( newtonsoftWritablePropertyResponse.Value, newtonsoftWritablePropertyResponse.AckCode, @@ -189,7 +189,7 @@ public bool TryGetValue(string key, out T value) return true; } - var writablePropertyValue = newtonsoftWritablePropertyResponse.Value; + object writablePropertyValue = newtonsoftWritablePropertyResponse.Value; // If the object is of type T or can be cast or converted to type T, go ahead and return it. if (ObjectConversionHelpers.TryCastOrConvert(writablePropertyValue, Convention, out value)) @@ -215,7 +215,6 @@ public bool TryGetValue(string key, out T value) } } - value = default; return false; } diff --git a/shared/src/ConventionBasedConstants.cs b/shared/src/ConventionBasedConstants.cs index 2313acf92e..14f8579644 100644 --- a/shared/src/ConventionBasedConstants.cs +++ b/shared/src/ConventionBasedConstants.cs @@ -4,7 +4,7 @@ namespace Microsoft.Azure.Devices.Shared { /// - /// Container for common convention based constants. + /// Common convention based constants. /// public static class ConventionBasedConstants { @@ -29,17 +29,17 @@ public static class ConventionBasedConstants public const string ValuePropertyName = "value"; /// - /// Represents the JSON document property name for the Ack Code of a writable property response. + /// Represents the JSON document property name for the acknowledgement code of a writable property response. /// public const string AckCodePropertyName = "ac"; /// - /// Represents the JSON document property name for the Ack Version of a writable property response. + /// Represents the JSON document property name for the acknowledgement version of a writable property response. /// public const string AckVersionPropertyName = "av"; /// - /// Represents the JSON document property name for the Ack Description of a writable property response. + /// Represents the JSON document property name for the acknowledgement description of a writable property response. /// public const string AckDescriptionPropertyName = "ad"; } diff --git a/shared/src/DefaultPayloadConvention.cs b/shared/src/DefaultPayloadConvention.cs index 749fb31a13..bdb5cef08e 100644 --- a/shared/src/DefaultPayloadConvention.cs +++ b/shared/src/DefaultPayloadConvention.cs @@ -14,7 +14,7 @@ public sealed class DefaultPayloadConvention : PayloadConvention /// /// A static instance of this class. /// - public static readonly DefaultPayloadConvention Instance = new DefaultPayloadConvention(); + public static DefaultPayloadConvention Instance { get; } = new DefaultPayloadConvention(); /// public override PayloadSerializer PayloadSerializer { get; } = NewtonsoftJsonPayloadSerializer.Instance; diff --git a/shared/src/NewtonsoftJsonPayloadSerializer.cs b/shared/src/NewtonsoftJsonPayloadSerializer.cs index 349c76676b..9760442ac6 100644 --- a/shared/src/NewtonsoftJsonPayloadSerializer.cs +++ b/shared/src/NewtonsoftJsonPayloadSerializer.cs @@ -7,7 +7,7 @@ namespace Microsoft.Azure.Devices.Shared { /// - /// A implementation. + /// A PayloadSerializer implementation. /// public class NewtonsoftJsonPayloadSerializer : PayloadSerializer { @@ -19,7 +19,7 @@ public class NewtonsoftJsonPayloadSerializer : PayloadSerializer /// /// The default instance of this class. /// - public static readonly NewtonsoftJsonPayloadSerializer Instance = new NewtonsoftJsonPayloadSerializer(); + public static NewtonsoftJsonPayloadSerializer Instance { get; } = new NewtonsoftJsonPayloadSerializer(); /// public override string ContentType => ApplicationJson; @@ -39,18 +39,23 @@ public override T DeserializeToType(string stringToDeserialize) /// public override T ConvertFromObject(object objectToConvert) { - var token = JToken.FromObject(objectToConvert); + if (objectToConvert == null) + { + return default; + } - return objectToConvert == null + var jToken = JToken.FromObject(objectToConvert); + return jToken == null ? default - : token.ToObject(); + : jToken.ToObject(); } /// public override bool TryGetNestedObjectValue(object nestedObject, string propertyName, out T outValue) { outValue = default; - if (nestedObject == null || string.IsNullOrEmpty(propertyName)) + if (nestedObject == null + || string.IsNullOrEmpty(propertyName)) { return false; } @@ -62,7 +67,8 @@ public override bool TryGetNestedObjectValue(object nestedObject, string prop ? DeserializeToType((string)nestedObject) : nestedObject as JObject; - if (nestedObjectAsJObject != null && nestedObjectAsJObject.TryGetValue(propertyName, out JToken element)) + if (nestedObjectAsJObject != null + && nestedObjectAsJObject.TryGetValue(propertyName, out JToken element)) { outValue = element.ToObject(); return true; @@ -72,6 +78,7 @@ public override bool TryGetNestedObjectValue(object nestedObject, string prop { // Catch and ignore any exceptions caught } + return false; } diff --git a/shared/src/PayloadConvention.cs b/shared/src/PayloadConvention.cs index 468083e9c1..ade7fc2345 100644 --- a/shared/src/PayloadConvention.cs +++ b/shared/src/PayloadConvention.cs @@ -6,9 +6,11 @@ namespace Microsoft.Azure.Devices.Shared /// /// The payload convention class. /// - /// The payload convention is used to define a specific serializer as well as a specific content encoding. - /// For example, IoT has a convention that is designed - /// to make it easier to get started with products that use specific conventions by default. + /// + /// The payload convention is used to define a specific serializer as well as a specific content encoding. + /// For example, Azure IoT has a Plug and Play convention + /// that is designed to make it easier to get started with products that use specific conventions by default. + /// public abstract class PayloadConvention { /// @@ -26,8 +28,8 @@ public abstract class PayloadConvention /// /// Returns the byte array for the convention-based message. /// - /// This base class will use the and to create this byte array. - /// The convention-based message that is to be sent. + /// This will use the and to create the byte array. + /// The convention-based message to be sent. /// The correctly encoded object for this convention. public virtual byte[] GetObjectBytes(object objectToSendWithConvention) { diff --git a/shared/src/PayloadEncoder.cs b/shared/src/PayloadEncoder.cs index 03b5c8bb72..b6f3cc622f 100644 --- a/shared/src/PayloadEncoder.cs +++ b/shared/src/PayloadEncoder.cs @@ -6,12 +6,12 @@ namespace Microsoft.Azure.Devices.Shared { /// - /// This class specifies the byte encoding for the payload. + /// Specifies the byte encoding for the payload. /// /// - /// The encoder is responsible for encoding all of your objects into the correct bytes for the that uses it. + /// The encoder is responsible for encoding all objects into the correct bytes for the that uses it. /// - /// By default we have implemented the class that uses + /// By default, there are implementations of the class that uses /// to handle the encoding for the class. /// /// diff --git a/shared/src/PayloadSerializer.cs b/shared/src/PayloadSerializer.cs index 15e7ee435f..d258e061ed 100644 --- a/shared/src/PayloadSerializer.cs +++ b/shared/src/PayloadSerializer.cs @@ -7,18 +7,21 @@ namespace Microsoft.Azure.Devices.Shared /// Provides the serialization for a specified convention. /// /// - /// The serializer is responsible for converting all of your objects into the correct format for the that uses it. + /// The serializer is responsible for converting all objects into the correct format for the that uses it. /// - /// By default we have implemented the class that uses + /// By default there are implementions the class that uses /// to handle the serialization for the class. /// /// public abstract class PayloadSerializer { /// - /// Used to specify what type of content to expect. + /// Used to specify what type of content will be in the payload. /// - /// This can be free-form but should adhere to standard MIME types. For example, "application/json" is what we implement by default. + /// + /// This can be free-form but should adhere to standard MIME types, + /// for example: "application/json". + /// /// A string representing the content type to use when sending a payload. public abstract string ContentType { get; } @@ -32,17 +35,19 @@ public abstract class PayloadSerializer /// /// Convert the serialized string to an object. /// - /// The type you want to return. - /// String to deserialize. + /// The type to return. + /// The string to deserialize. /// A fully deserialized type. public abstract T DeserializeToType(string stringToDeserialize); /// /// Converts the object using the serializer. /// - /// This class is used by the PayloadCollection-based classes to attempt to convert from the native serializer type + /// + /// This class is used by the PayloadCollection-based classes to attempt to convert from the native serializer type /// (for example, JObject or JsonElement) to the desired type. - /// When you implement this you need to be aware of what type your serializer will use for anonymous types. + /// When implementing this, be aware of what type the serializer will use for anonymous types. + /// /// The type to convert to. /// The object to convert. /// A converted object @@ -52,15 +57,15 @@ public abstract class PayloadSerializer /// Gets a nested property from the serialized data. /// /// - /// This is used internally by our PayloadCollection-based classes to attempt to get a property of the underlying object. + /// This is used by the PayloadCollection-based classes to attempt to get a property of the underlying object. /// An example of this would be a property under the component. /// /// The type to convert the retrieved property to. /// The object that might contain the nested property. /// This needs to be in the json object equivalent format as required by the serializer or the string representation of it. /// The name of the property to be retrieved. - /// True if the nested object contains an element with the specified key; otherwise, it returns false. - /// + /// The retrieved value. + /// True if the nested object contains an element with the specified key, otherwise false. public abstract bool TryGetNestedObjectValue(object nestedObject, string propertyName, out T outValue); /// @@ -69,7 +74,7 @@ public abstract class PayloadSerializer /// The value of the property. /// The status code of the write operation. /// The version the property is responding to. - /// An optional description of the writable property response. + /// An optional response description to the writable property request. /// The writable property response to be used with this serializer. public abstract IWritablePropertyResponse CreateWritablePropertyResponse(object value, int statusCode, long version, string description = default); } diff --git a/shared/src/Utf8PayloadEncoder.cs b/shared/src/Utf8PayloadEncoder.cs index 0330c3fcf2..b7efbb1153 100644 --- a/shared/src/Utf8PayloadEncoder.cs +++ b/shared/src/Utf8PayloadEncoder.cs @@ -6,14 +6,14 @@ namespace Microsoft.Azure.Devices.Shared { /// - /// A UTF-8 implementation. + /// A UTF-8 PayloadEncoder implementation. /// public class Utf8PayloadEncoder : PayloadEncoder { /// /// The default instance of this class. /// - public static readonly Utf8PayloadEncoder Instance = new Utf8PayloadEncoder(); + public static Utf8PayloadEncoder Instance { get; } = new Utf8PayloadEncoder(); /// public override Encoding ContentEncoding => Encoding.UTF8;