Use the Azure.Core ETag type in the DPS service client

SDK v2 migration guide.md

@@ -217,6 +217,7 @@ to migrate to version 2.x when they have the chance. For more details on LTS rel
 #### Other notable breaking changes
 
 - Query methods (like for individual and group enrollments) now take a query string (and optionally a page size parameter), and the `Query` result no longer requires disposing.
+- ETag fields on the classes `IndividualEnrollment`, `EnrollmentGroup`, and `DeviceRegistrationState` are now taken as the `Azure.ETag` type instead of strings.
 
 ### Authentication provider client
 

iothub/device/src/Transport/Http/HttpClientHelper.cs

@@ -99,19 +99,7 @@ private static async Task<T> ReadResponseMessageAsync<T>(HttpResponseMessage mes
                 return (T)(object)message;
             }
 
-            T entity = await ReadAsAsync<T>(message.Content, token).ConfigureAwait(false);
-
-            // ETag in the header is considered authoritative
-            if (entity is IETagHolder eTagHolder)
-            {
-                if (message.Headers.ETag != null && !string.IsNullOrWhiteSpace(message.Headers.ETag.Tag))
-                {
-                    // RDBug 3429280:Make the version field of Device object internal
-                    eTagHolder.ETag = message.Headers.ETag.Tag;
-                }
-            }
-
-            return entity;
+            return await ReadAsAsync<T>(message.Content, token).ConfigureAwait(false);
         }
 
         private static void AddCustomHeaders(HttpRequestMessage requestMessage, IDictionary<string, string> customHeaders)

provisioning/service/src/DeviceRegistrationsClient.cs

@@ -7,6 +7,7 @@
 using System.Net;
 using System.Threading.Tasks;
 using System.Threading;
+using Azure;
 using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
@@ -60,7 +61,7 @@ public async Task<DeviceRegistrationState> GetAsync(string registrationId, Cance
                     GetDeviceRegistrationStatusUri(registrationId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 

provisioning/service/src/EnrollmentGroupsClient.cs

@@ -8,6 +8,7 @@
 using System.Net;
 using System.Threading.Tasks;
 using System.Threading;
+using Azure;
 using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
@@ -101,7 +102,7 @@ public async Task<EnrollmentGroup> GetAsync(string enrollmentGroupId, Cancellati
                     GetEnrollmentUri(enrollmentGroupId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
@@ -131,7 +132,7 @@ await _contractApiHttp
                     GetEnrollmentUri(enrollmentGroupId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
         }
@@ -201,7 +202,7 @@ public async Task<BulkEnrollmentOperationResult> RunBulkOperationAsync(
                     GetEnrollmentUri(),
                     null,
                     JsonConvert.SerializeObject(bulkOperation),
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
@@ -257,7 +258,7 @@ public async Task<AttestationMechanism> GetAttestationAsync(string enrollmentGro
                     GetEnrollmentAttestationUri(enrollmentGroupId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 

provisioning/service/src/Http/ContractApiHttp.cs

@@ -12,6 +12,7 @@
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
+using Azure;
 using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
@@ -95,7 +96,7 @@ public ContractApiHttp(
         /// <param name="requestUri">the rest API <see cref="Uri"/> with for the requested service.</param>
         /// <param name="customHeaders">the optional Dictionary with additional header fields. It can be null.</param>
         /// <param name="body">the string with the message body. It can be null or empty.</param>
-        /// <param name="ifMatch">the optional string with the match condition, normally an eTag. It can be null.</param>
+        /// <param name="eTag">the optional string with the match condition, normally an eTag. It can be null.</param>
         /// <param name="cancellationToken">the task cancellation Token.</param>
         /// <returns>The <see cref="ContractApiResponse"/> with the HTTP response.</returns>
         /// <exception cref="OperationCanceledException">If the cancellation was requested.</exception>
@@ -106,7 +107,7 @@ public async Task<ContractApiResponse> RequestAsync(
             Uri requestUri,
             IDictionary<string, string> customHeaders,
             string body,
-            string ifMatch,
+            ETag eTag,
             CancellationToken cancellationToken)
         {
             ContractApiResponse response;
@@ -127,7 +128,12 @@ public async Task<ContractApiResponse> RequestAsync(
                         msg.Headers.Add(header.Key, header.Value);
                     }
                 }
-                InsertIfMatch(msg, ifMatch);
+
+                if (!string.IsNullOrWhiteSpace(eTag.ToString()))
+                {
+                    string escapedETag = EscapeETag(eTag.ToString());
+                    msg.Headers.IfMatch.Add(new EntityTagHeaderValue(escapedETag));
+                }
 
                 try
                 {
@@ -217,28 +223,25 @@ private static void ValidateHttpResponse(ContractApiResponse response)
             }
         }
 
-        private static void InsertIfMatch(HttpRequestMessage requestMessage, string ifMatch)
+        // ETag values other than "*" need to be wrapped in escaped quotes if they are not
+        // already.
+        private static string EscapeETag(string eTag)
         {
-            if (string.IsNullOrWhiteSpace(ifMatch))
-            {
-                return;
-            }
-
-            var quotedIfMatch = new StringBuilder();
+            var escapedETagBuilder = new StringBuilder();
 
-            if (!ifMatch.StartsWith("\"", StringComparison.OrdinalIgnoreCase))
+            if (!eTag.StartsWith("\"", StringComparison.OrdinalIgnoreCase))
             {
-                quotedIfMatch.Append('"');
+                escapedETagBuilder.Append('"');
             }
 
-            quotedIfMatch.Append(ifMatch);
+            escapedETagBuilder.Append(eTag);
 
-            if (!ifMatch.EndsWith("\"", StringComparison.OrdinalIgnoreCase))
+            if (!eTag.EndsWith("\"", StringComparison.OrdinalIgnoreCase))
             {
-                quotedIfMatch.Append('"');
+                escapedETagBuilder.Append('"');
             }
 
-            requestMessage.Headers.IfMatch.Add(new EntityTagHeaderValue(quotedIfMatch.ToString()));
+            return escapedETagBuilder.ToString();
         }
 
         /// <summary>

provisioning/service/src/Http/IContractApiHttp.cs

@@ -6,6 +6,7 @@
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
+using Azure;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
 {
@@ -16,7 +17,7 @@ Task<ContractApiResponse> RequestAsync(
             Uri requestUri,
             IDictionary<string, string> customHeaders,
             string body,
-            string ifMatch,
+            ETag ifMatch,
             CancellationToken cancellationToken);
     }
 }

provisioning/service/src/IndividualEnrollmentsClient.cs

@@ -9,6 +9,7 @@
 using System.Threading.Tasks;
 using System.Threading;
 using Newtonsoft.Json;
+using Azure;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
 {
@@ -91,7 +92,7 @@ public async Task<IndividualEnrollment> GetAsync(string registrationId, Cancella
                     GetEnrollmentUri(registrationId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
@@ -121,7 +122,7 @@ await _contractApiHttp
                     GetEnrollmentUri(registrationId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
         }
@@ -191,7 +192,7 @@ public async Task<BulkEnrollmentOperationResult> RunBulkOperationAsync(
                     GetEnrollmentUri(),
                     null,
                     JsonConvert.SerializeObject(bulkOperation),
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
@@ -248,7 +249,7 @@ public async Task<AttestationMechanism> GetAttestationAsync(string registrationI
                     GetEnrollmentAttestationUri(registrationId),
                     null,
                     null,
-                    null,
+                    new ETag(),
                     cancellationToken)
                 .ConfigureAwait(false);
 

provisioning/service/src/Microsoft.Azure.Devices.Provisioning.Service.csproj

@@ -43,6 +43,7 @@
 
   <!--Nuget package dependencies-->
   <ItemGroup>
+    <PackageReference Include="Azure.Core" Version="1.25.0" />
     <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="6.0.0">
       <PrivateAssets>all</PrivateAssets>

provisioning/service/src/Models/DeviceRegistrationState.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using Azure;
 using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service
@@ -72,6 +73,7 @@ public DeviceRegistrationState(string registrationId)
         /// Registration status ETag.
         /// </summary>
         [JsonProperty(PropertyName = "etag", DefaultValueHandling = DefaultValueHandling.Ignore)]
-        public string ETag { get; internal set; }
+        [JsonConverter(typeof(NewtonsoftJsonETagConverter))] // NewtonsoftJsonETagConverter is used here because otherwise the ETag isn't serialized properly
+        public ETag ETag { get; internal set; }
     }
 }

provisioning/service/src/Models/EnrollmentGroup.cs

@@ -6,6 +6,7 @@
 using System.ComponentModel;
 using System.Linq;
 using System.Net;
+using Azure;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Converters;
 
@@ -80,7 +81,7 @@ namespace Microsoft.Azure.Devices.Provisioning.Service
     /// }
     /// </code>
     /// </example>
-    public class EnrollmentGroup : IETagHolder
+    public class EnrollmentGroup
     {
         /// <summary>
         /// Creates a new instance of EnrollmentGroup.
@@ -121,54 +122,9 @@ public EnrollmentGroup(string enrollmentGroupId, Attestation attestation)
             Attestation = attestation;
         }
 
-        /// <summary>
-        /// Creates a new instance of EnrollmentGroup using information in a JSON.
-        /// </summary>
-        /// <remarks>
-        /// This constructor creates an instance of the enrollmentGroup filling the class with the information
-        /// provided in the JSON. It is used by the SDK to parse EnrollmentGroup responses from the provisioning service.
-        /// </remarks>
-        /// <example>
-        /// The following JSON is a sample of the EnrollmentGroup response, received from the provisioning service.
-        /// <code>
-        /// {
-        ///    "enrollmentGroupId":"validEnrollmentGroupId",
-        ///    "attestation":{
-        ///        "type":"x509",
-        ///        "signingCertificates":{
-        ///            "primary":{
-        ///                "certificate":"[valid certificate]",
-        ///                "info": {
-        ///                    "subjectName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
-        ///                    "sha1Thumbprint": "0000000000000000000000000000000000",
-        ///                    "sha256Thumbprint": "validEnrollmentGroupId",
-        ///                    "issuerName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
-        ///                    "notBeforeUtc": "2017-11-14T12:34:18Z",
-        ///                    "notAfterUtc": "2017-11-20T12:34:18Z",
-        ///                    "serialNumber": "000000000000000000",
-        ///                    "version": 3
-        ///                }
-        ///            }
-        ///        }
-        ///    },
-        ///    "iotHubHostName":"ContosoIoTHub.azure-devices.net",
-        ///    "provisioningStatus":"enabled",
-        ///    "createdDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
-        ///    "lastUpdatedDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
-        ///    "etag": "\"00000000-0000-0000-0000-00000000000\""
-        /// }
-        /// </code>
-        /// </example>
-        /// <param name="enrollmentGroupId">The string with a unique id for the enrollmentGroup. It cannot be null or empty.</param>
-        /// <param name="attestation">The <see cref="AttestationMechanism"/> for the enrollment. It shall be `X509` or `SymmetricKey`.</param>
-        /// <param name="iotHubHostName">The string with the target IoT hub name. This is optional and can be null or empty.</param>
-        /// <param name="initialTwinState">The <see cref="TwinState"/> with the initial Twin condition. This is optional and can be null.</param>
-        /// <param name="provisioningStatus">The <see cref="ProvisioningStatus"/> that determine the initial status of the device. This is optional and can be null.</param>
-        /// <param name="createdDateTimeUtc">The DateTime with the date and time that the enrollment was created. This is optional and can be null.</param>
-        /// <param name="lastUpdatedDateTimeUtc">The DateTime with the date and time that the enrollment was updated. This is optional and can be null.</param>
-        /// <param name="eTag">The string with the eTag that identify the correct instance of the enrollment in the service. It cannot be null or empty.</param>
-        /// <param name="capabilities">The capabilities of the device (ie: is it an edge device?)</param>
-        /// <exception cref="DeviceProvisioningServiceException">If the received JSON is invalid.</exception>
+        // This JsonConstructor is used for serialization instead of the usual empty constructor
+        // because one of this object's fields (attestation) doesn't map 1:1 with where that field
+        // is in the JSON the service sends.
         [JsonConstructor]
         internal EnrollmentGroup(
             string enrollmentGroupId,
@@ -178,30 +134,23 @@ internal EnrollmentGroup(
             ProvisioningStatus? provisioningStatus,
             DateTime createdDateTimeUtc,
             DateTime lastUpdatedDateTimeUtc,
-            string eTag,
+            ETag eTag,
             DeviceCapabilities capabilities)
         {
             if (attestation == null)
             {
-                throw new DeviceProvisioningServiceException("Service responds an enrollmentGroup without attestation.", HttpStatusCode.BadRequest);
+                throw new DeviceProvisioningServiceException("Service responded with an enrollment without attestation.", HttpStatusCode.BadRequest);
             }
 
-            try
-            {
-                EnrollmentGroupId = enrollmentGroupId;
-                Attestation = attestation.GetAttestation();
-                IotHubHostName = iotHubHostName;
-                InitialTwinState = initialTwinState;
-                ProvisioningStatus = provisioningStatus;
-                CreatedDateTimeUtc = createdDateTimeUtc;
-                LastUpdatedDateTimeUtc = lastUpdatedDateTimeUtc;
-                ETag = eTag;
-                Capabilities = capabilities;
-            }
-            catch (ArgumentException e)
-            {
-                throw new DeviceProvisioningServiceException(e.Message, HttpStatusCode.BadRequest, e);
-            }
+            EnrollmentGroupId = enrollmentGroupId;
+            Attestation = attestation.GetAttestation(); // This is the one reason why we can't use an empty constructor here.
+            IotHubHostName = iotHubHostName;
+            InitialTwinState = initialTwinState;
+            ProvisioningStatus = provisioningStatus;
+            CreatedDateTimeUtc = createdDateTimeUtc;
+            LastUpdatedDateTimeUtc = lastUpdatedDateTimeUtc;
+            ETag = eTag;
+            Capabilities = capabilities;
         }
 
         /// <summary>
@@ -304,7 +253,8 @@ public Attestation Attestation
         /// Enrollment's ETag.
         /// </summary>
         [JsonProperty(PropertyName = "etag", DefaultValueHandling = DefaultValueHandling.Ignore)]
-        public string ETag { get; set; }
+        [JsonConverter(typeof(NewtonsoftJsonETagConverter))] // NewtonsoftJsonETagConverter is used here because otherwise the ETag isn't serialized properly
+        public ETag ETag { get; set; }
 
         /// <summary>
         /// Capabilities of the device.