Clean-up DPS service group enrollment sample and related documentation

Azure · Jan 12, 2023 · ad393c8 · ad393c8
1 parent a2e9b75
commit ad393c8
Show file tree

Hide file tree

Showing 12 changed files with 73 additions and 88 deletions.
diff --git a/azureiot.sln b/azureiot.sln
@@ -180,7 +180,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CleanupEnrollmentsSample",
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "EnrollmentGroupSample", "provisioning\service\samples\getting started\EnrollmentGroupSample\EnrollmentGroupSample.csproj", "{EDE1FB8E-5BD4-49E7-9745-6599687D34CD}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "EnrollmentSample", "provisioning\service\samples\getting started\EnrollmentSample\EnrollmentSample.csproj", "{C8639C47-5772-4E58-A5A1-9D4134577437}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "IndividualEnrollmentSample", "provisioning\service\samples\getting started\EnrollmentSample\IndividualEnrollmentSample.csproj", "{C8639C47-5772-4E58-A5A1-9D4134577437}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "how to guides", "how to guides", "{E6205B13-D163-4247-80F5-905ACC7F0977}"
 EndProject

diff --git a/provisioning/service/samples/getting started/EnrollmentGroupSample/EnrollmentGroupSample.cs b/provisioning/service/samples/getting started/EnrollmentGroupSample/EnrollmentGroupSample.cs
@@ -3,91 +3,88 @@
 
 using System;
 using System.Linq;
-using System.Security.Cryptography.X509Certificates;
 using System.Threading.Tasks;
+using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
 {
     internal class EnrollmentGroupSample
     {
-        private const string EnrollmentGroupId = "enrollmentgrouptest";
+        private static readonly string s_enrollmentGroupId = $"EnrollmentGroupSample-{Guid.NewGuid()}";
         private readonly ProvisioningServiceClient _provisioningServiceClient;
-        private readonly X509Certificate2 _groupIssuerCertificate;
 
-        public EnrollmentGroupSample(ProvisioningServiceClient provisioningServiceClient, X509Certificate2 groupIssuerCertificate)
+        public EnrollmentGroupSample(ProvisioningServiceClient provisioningServiceClient)
         {
             _provisioningServiceClient = provisioningServiceClient;
-            _groupIssuerCertificate = groupIssuerCertificate;
         }
 
         public async Task RunSampleAsync()
         {
-            await QueryEnrollmentGroupAsync().ConfigureAwait(false);
+            await CreateEnrollmentGroupAsync();
+            await GetEnrollmentGroupInfoAsync();
+            await QueryEnrollmentGroupAsync();
+            await DeleteEnrollmentGroupAsync();
+        }
+
+        public async Task CreateEnrollmentGroupAsync()
+        {
+            Console.WriteLine("Creating a new enrollment group...");
+            Attestation attestation = new SymmetricKeyAttestation(null, null); // let the service generate keys
+            var group = new EnrollmentGroup(s_enrollmentGroupId, attestation);
 
-            await CreateEnrollmentGroupAsync().ConfigureAwait(false);
-            await GetEnrollmentGroupInfoAsync().ConfigureAwait(false);
-            await DeleteEnrollmentGroupAsync().ConfigureAwait(false);
+            group = await _provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(group);
+            Console.WriteLine($"Created {group.EnrollmentGroupId}: {JsonConvert.SerializeObject(group)}");
+        }
+
+        public async Task GetEnrollmentGroupInfoAsync()
+        {
+            Console.WriteLine("Getting the enrollment group information...");
+            EnrollmentGroup group = await _provisioningServiceClient.GetEnrollmentGroupAsync(s_enrollmentGroupId);
+            Console.WriteLine($"Got {group.EnrollmentGroupId}: {JsonConvert.SerializeObject(group)}");
         }
 
         public async Task QueryEnrollmentGroupAsync()
         {
-            Console.WriteLine("\nCreating a query for enrollmentGroups...");
             var querySpecification = new QuerySpecification("SELECT * FROM enrollmentGroups");
+            Console.WriteLine($"Running a query for enrollment groups: {querySpecification.Query}");
             using Query query = _provisioningServiceClient.CreateEnrollmentGroupQuery(querySpecification);
             while (query.HasNext())
             {
-                Console.WriteLine("\nQuerying the next enrollmentGroups...");
-                QueryResult queryResult = await query.NextAsync().ConfigureAwait(false);
-                Console.WriteLine(queryResult);
-
+                QueryResult queryResult = await query.NextAsync();
                 foreach (EnrollmentGroup group in queryResult.Items.Cast<EnrollmentGroup>())
                 {
+                    Console.WriteLine($"Found enrollment group {group.EnrollmentGroupId} is {group.ProvisioningStatus}.");
                     await EnumerateRegistrationsInGroupAsync(querySpecification, group);
                 }
             }
         }
 
         private async Task EnumerateRegistrationsInGroupAsync(QuerySpecification querySpecification, EnrollmentGroup group)
         {
-            Console.WriteLine($"\nCreating a query for registrations within group '{group.EnrollmentGroupId}'...");
-            using Query registrationQuery = _provisioningServiceClient.CreateEnrollmentGroupRegistrationStateQuery(querySpecification, group.EnrollmentGroupId);
-            Console.WriteLine($"\nQuerying the next registrations within group '{group.EnrollmentGroupId}'...");
-            while (registrationQuery.HasNext())
+            Console.WriteLine($"Registrations within group {group.EnrollmentGroupId}:");
+            using Query query = _provisioningServiceClient.CreateEnrollmentGroupRegistrationStateQuery(
+                querySpecification,
+                group.EnrollmentGroupId);
+
+            while (query.HasNext())
             {
-                QueryResult registrationQueryResult = await registrationQuery.NextAsync();
-                Console.WriteLine(registrationQueryResult.ToString());
+                QueryResult queryResult = await query.NextAsync();
+                foreach (DeviceRegistrationState registration in queryResult.Items.Cast<DeviceRegistrationState>())
+                {
+                    Console.WriteLine($"\t{registration.RegistrationId} for {registration.DeviceId} is {registration.Status}.");
+                    if (registration.ErrorCode.HasValue)
+                    {
+                        Console.WriteLine($"\t\tWith error ({registration.ErrorCode.Value}: {registration.ErrorMessage}");
+                    }
+                }
             }
         }
 
-        public async Task CreateEnrollmentGroupAsync()
-        {
-            Console.WriteLine("\nCreating a new enrollmentGroup...");
-            Attestation attestation = X509Attestation.CreateFromRootCertificates(_groupIssuerCertificate);
-            var enrollmentGroup =
-                    new EnrollmentGroup(
-                            EnrollmentGroupId,
-                            attestation);
-            Console.WriteLine(enrollmentGroup);
-
-            Console.WriteLine("\nAdding new enrollmentGroup...");
-            EnrollmentGroup enrollmentGroupResult =
-                await _provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(enrollmentGroup);
-            Console.WriteLine("\nEnrollmentGroup created with success.");
-            Console.WriteLine(enrollmentGroupResult);
-        }
-
-        public async Task GetEnrollmentGroupInfoAsync()
-        {
-            Console.WriteLine("\nGetting the enrollmentGroup information...");
-            EnrollmentGroup getResult =
-                await _provisioningServiceClient.GetEnrollmentGroupAsync(EnrollmentGroupId);
-            Console.WriteLine(getResult);
-        }
-
         public async Task DeleteEnrollmentGroupAsync()
         {
-            Console.WriteLine("\nDeleting the enrollmentGroup...");
-            await _provisioningServiceClient.DeleteEnrollmentGroupAsync(EnrollmentGroupId);
+            Console.WriteLine("Deleting the enrollmentGroup...");
+            await _provisioningServiceClient.DeleteEnrollmentGroupAsync(s_enrollmentGroupId);
+            Console.WriteLine($"Enrollment group {s_enrollmentGroupId} deleted.");
         }
     }
 }
diff --git a/provisioning/service/samples/getting started/EnrollmentGroupSample/Parameters.cs b/provisioning/service/samples/getting started/EnrollmentGroupSample/Parameters.cs
@@ -8,13 +8,6 @@ namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
     /// </summary>
     internal class Parameters
     {
-        [Option(
-            'p',
-            "CertificatePath",
-            Required = true,
-            HelpText = "The path to X509 certificate.")]
-        public string CertificatePath { get; set; }
-
         [Option(
             'c',
             "ProvisioningConnectionString",

diff --git a/provisioning/service/samples/getting started/EnrollmentGroupSample/Program.cs b/provisioning/service/samples/getting started/EnrollmentGroupSample/Program.cs
@@ -3,7 +3,7 @@
 
 using CommandLine;
 using System;
-using System.Security.Cryptography.X509Certificates;
+using System.Threading.Tasks;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
 {
@@ -16,7 +16,7 @@ internal class Program
         /// <param name="args">
         /// Run with `--help` to see a list of required and optional parameters.
         /// </param>
-        public static int Main(string[] args)
+        public static async Task Main(string[] args)
         {
             // Parse application parameters
             Parameters parameters = null;
@@ -36,14 +36,11 @@ public static int Main(string[] args)
                 Environment.Exit(1);
             }
 
-            var certificate = new X509Certificate2(parameters.CertificatePath);
-
             using var provisioningServiceClient = ProvisioningServiceClient.CreateFromConnectionString(parameters.ProvisioningConnectionString);
-            var sample = new EnrollmentGroupSample(provisioningServiceClient, certificate);
-            sample.RunSampleAsync().GetAwaiter().GetResult();
+            var sample = new EnrollmentGroupSample(provisioningServiceClient);
+            await sample.RunSampleAsync();
 
             Console.WriteLine("Done.\n");
-            return 0;
         }
     }
 }
diff --git a/...rted/EnrollmentSample/EnrollmentSample.cs → ...lmentSample/IndividualEnrollmentSample.cs b/...rted/EnrollmentSample/EnrollmentSample.cs → ...lmentSample/IndividualEnrollmentSample.cs
@@ -7,7 +7,7 @@
 
 namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
 {
-    internal class EnrollmentSample
+    internal class IndividualEnrollmentSample
     {
         private const string RegistrationId = "myvalid-registratioid-csharp";
         private const string TpmEndorsementKey =
@@ -25,7 +25,7 @@ internal class EnrollmentSample
 
         private readonly ProvisioningServiceClient _provisioningServiceClient;
 
-        public EnrollmentSample(ProvisioningServiceClient provisioningServiceClient)
+        public IndividualEnrollmentSample(ProvisioningServiceClient provisioningServiceClient)
         {
             _provisioningServiceClient = provisioningServiceClient;
         }

diff --git a/.../EnrollmentSample/EnrollmentSample.csproj → ...tSample/IndividualEnrollmentSample.csproj b/.../EnrollmentSample/EnrollmentSample.csproj → ...tSample/IndividualEnrollmentSample.csproj
@@ -1,8 +1,8 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <LangVersion>9.0</LangVersion>
   </PropertyGroup>
 

diff --git a/provisioning/service/samples/getting started/EnrollmentSample/Parameters.cs b/provisioning/service/samples/getting started/EnrollmentSample/Parameters.cs
@@ -1,11 +1,7 @@
 using System;
-using System.Collections.Generic;
-using System.Text;
-using CommandLine.Text;
 using CommandLine;
-using Newtonsoft.Json;
 
-namespace EnrollmentSample
+namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
 {
     internal class Parameters
     {

diff --git a/provisioning/service/samples/getting started/EnrollmentSample/Program.cs b/provisioning/service/samples/getting started/EnrollmentSample/Program.cs
@@ -2,14 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using System.Threading.Tasks;
 using CommandLine;
-using EnrollmentSample;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service.Samples
 {
     internal class Program
     {
-        public static int Main(string[] args)
+        public static async Task Main(string[] args)
         {
             // Parse application parameters
             Parameters parameters = null;
@@ -30,11 +30,10 @@ public static int Main(string[] args)
             }
 
             using var provisioningServiceClient = ProvisioningServiceClient.CreateFromConnectionString(parameters.ProvisioningConnectionString);
-            var sample = new EnrollmentSample(provisioningServiceClient);
-            sample.RunSampleAsync().GetAwaiter().GetResult();
+            var sample = new IndividualEnrollmentSample(provisioningServiceClient);
+            await sample.RunSampleAsync();
 
             Console.WriteLine("Done.\n");
-            return 0;
         }
     }
 }
diff --git a/.../service/samples/getting started/EnrollmentSample/Properties/launchSettings.json.template b/.../service/samples/getting started/EnrollmentSample/Properties/launchSettings.json.template
diff --git a/provisioning/service/samples/readme.md b/provisioning/service/samples/readme.md
@@ -4,7 +4,7 @@
 
 - [Group certificate verification][group-cert-sample] sample
 - [Bulk operation][bulk-op-sample] sample
-- [Enrollment][enrollment-sample] sample
+- [Individual enrollment][enrollment-sample] sample
 - [Enrollment group][enrollment-group-sample] sample
 - [Clean up enrollments][clean-up-enrollments-sample] sample
 

diff --git a/provisioning/service/src/Config/DeviceRegistrationState.cs b/provisioning/service/src/Config/DeviceRegistrationState.cs
@@ -2,7 +2,6 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
-using Microsoft.Azure.Devices.Shared;
 using Newtonsoft.Json;
 
 namespace Microsoft.Azure.Devices.Provisioning.Service

diff --git a/provisioning/service/src/Config/QueryResult.cs b/provisioning/service/src/Config/QueryResult.cs
@@ -77,6 +77,20 @@ public class QueryResult
         /// <summary>
         /// Getter for the list of query result Items.
         /// </summary>
+        /// <remarks>
+        /// Depending on the <see cref="Type"/>, these items can be cast to a corresponding type:
+        /// <list type="bullet">
+        /// <item><description>
+        /// <see cref="QueryResultType.Enrollment"/>: <see cref="IndividualEnrollment"/>
+        /// </description></item>
+        /// <item><description>
+        /// <see cref="QueryResultType.EnrollmentGroup"/>: <see cref="EnrollmentGroup"/>
+        /// </description></item>
+        /// <item><description>
+        /// <see cref="QueryResultType.DeviceRegistration"/>: <see cref="DeviceRegistrationState"/>
+        /// </description></item>
+        /// </list>
+        /// </remarks>
         public IEnumerable<object> Items { get; private set; }
 
         /// <summary>