ADT C# SDK Samples Improvements (#12683)

* fix(samples): improve on the snippet comments

* Create a relationship samples

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/ComponentSamples.cs

@@ -42,7 +42,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
                     newComponentModelPayload,
                     newModelPayload
                 });
-            Console.WriteLine($"Created models Ids {componentModelId} and {modelId} with response {createModelsResponse.GetRawResponse().Status}.");
+            Console.WriteLine($"Created models with Ids {componentModelId} and {modelId}. Response status: {createModelsResponse.GetRawResponse().Status}.");
 
             #region Snippet:DigitalTwinsSampleCreateBasicTwin
 
@@ -77,7 +77,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
             string basicDtPayload = JsonSerializer.Serialize(basicTwin);
 
             Response<string> createBasicDtResponse = await client.CreateDigitalTwinAsync(basicDtId, basicDtPayload);
-            Console.WriteLine($"Created digital twin {basicDtId} with response {createBasicDtResponse.GetRawResponse().Status}.");
+            Console.WriteLine($"Created digital twin with Id {basicDtId}. Response status: {createBasicDtResponse.GetRawResponse().Status}.");
 
             #endregion Snippet:DigitalTwinsSampleCreateBasicTwin
 
@@ -129,7 +129,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
             string dt2Payload = JsonSerializer.Serialize(customTwin);
 
             Response<string> createCustomDtResponse = await client.CreateDigitalTwinAsync(customDtId, dt2Payload);
-            Console.WriteLine($"Created digital twin {customDtId} with response {createCustomDtResponse.GetRawResponse().Status}.");
+            Console.WriteLine($"Created digital twin with Id {customDtId}. Response status: {createCustomDtResponse.GetRawResponse().Status}.");
 
             #endregion Snippet:DigitalTwinsSampleCreateCustomTwin
 
@@ -161,7 +161,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
 
             Response<string> response = await client.UpdateComponentAsync(basicDtId, "Component1", updatePayload);
 
-            Console.WriteLine($"Updated component for digital twin {basicDtId}. Update response status: {response.GetRawResponse().Status}");
+            Console.WriteLine($"Updated component for digital twin with Id {basicDtId}. Response status: {response.GetRawResponse().Status}");
 
             #endregion Snippet:DigitalTwinsSampleUpdateComponent
 
@@ -171,7 +171,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
 
             response = await client.GetComponentAsync(basicDtId, SamplesConstants.ComponentPath);
 
-            Console.WriteLine($"Get component for digital twin: \n{response.Value}. Get response status: {response.GetRawResponse().Status}");
+            Console.WriteLine($"Retrieved component for digital twin with Id {basicDtId}. Response status: {response.GetRawResponse().Status}");
 
             #endregion Snippet:DigitalTwinsSampleGetComponent
 

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/CustomRelationship.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+using Azure.DigitalTwins.Core.Serialization;
+
+namespace Azure.DigitalTwins.Core.Samples
+{
+    /// <summary>
+    /// Custom type for a sample illustrating how someone can create their own class to match a relationship type
+    /// for serialization, instead of using <see cref="BasicRelationship"/>.
+    /// </summary>
+    internal class CustomRelationship
+    {
+        [JsonPropertyName("$relationshipId")]
+        public string Id { get; set; }
+
+        [JsonPropertyName("$targetId")]
+        public string TargetId { get; set; }
+
+        [JsonPropertyName("$sourceId")]
+        public string SourceId { get; set; }
+
+        [JsonPropertyName("$relationshipName")]
+        public string Name { get; set; }
+
+        [JsonPropertyName("Prop1")]
+        public string Prop1 { get; set; }
+
+        [JsonPropertyName("Prop2")]
+        public int Prop2 { get; set; }
+    }
+}

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/DigitalTwinsLifecycleSamples.cs

@@ -117,8 +117,8 @@ private async Task DeleteAllModelsAsync()
 
                 foreach (string modelId in models)
                 {
-                    await client.DeleteModelAsync(modelId);
-                    Console.WriteLine($"Deleted model {modelId}");
+                    Response deleteModelResponse = await client.DeleteModelAsync(modelId);
+                    Console.WriteLine($"Deleted model with Id {modelId}. Response status: {deleteModelResponse.Status}");
                 }
             }
             catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
@@ -148,7 +148,7 @@ private async Task AddAllModelsAsync()
             try
             {
                 Response<IReadOnlyList<ModelData>> response = await client.CreateModelsAsync(modelsToCreate);
-                Console.WriteLine($"Created models status: {response.GetRawResponse().Status}");
+                Console.WriteLine($"Created models. Response status: {response.GetRawResponse().Status}");
             }
             catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
             {
@@ -175,7 +175,7 @@ public async Task GetAllModelsAsync()
                 AsyncPageable<ModelData> allModels = client.GetModelsAsync();
                 await foreach (ModelData model in allModels)
                 {
-                    Console.WriteLine($"Model Id: {model.Id}, display name: {model.DisplayName["en"]}, upload time: {model.UploadTime}, is decommissioned: {model.Decommissioned}");
+                    Console.WriteLine($"Retrieved model with Id {model.Id}, display name {model.DisplayName["en"]}, upload time {model.UploadTime}, and decommissioned: {model.Decommissioned}");
                 }
 
                 #endregion Snippet:DigitalTwinsSampleGetModels
@@ -199,43 +199,33 @@ public async Task DeleteTwinsAsync()
                 try
                 {
                     // Delete all relationships
-
-                    #region Snippet:DigitalTwinsSampleGetRelationships
-
                     AsyncPageable<string> relationships = client.GetRelationshipsAsync(twin.Key);
-
-                    #endregion Snippet:DigitalTwinsSampleGetRelationships
-
                     await foreach (var relationshipJson in relationships)
                     {
                         BasicRelationship relationship = JsonSerializer.Deserialize<BasicRelationship>(relationshipJson);
                         await client.DeleteRelationshipAsync(twin.Key, relationship.Id);
-                        Console.WriteLine($"Found and deleted relationship {relationship.Id}");
+                        Console.WriteLine($"Found and deleted relationship with Id {relationship.Id}.");
                     }
 
                     // Delete any incoming relationships
-
-                    #region Snippet:DigitalTwinsSampleGetIncomingRelationships
-
                     AsyncPageable<IncomingRelationship> incomingRelationships = client.GetIncomingRelationshipsAsync(twin.Key);
 
-                    #endregion Snippet:DigitalTwinsSampleGetIncomingRelationships
-
                     await foreach (IncomingRelationship incomingRelationship in incomingRelationships)
                     {
                         await client.DeleteRelationshipAsync(incomingRelationship.SourceId, incomingRelationship.RelationshipId);
-                        Console.WriteLine($"Found and deleted incoming relationship {incomingRelationship.RelationshipId}");
+                        Console.WriteLine($"Found and deleted incoming relationship with Id {incomingRelationship.RelationshipId}.");
                     }
 
                     // Now the digital twin should be safe to delete
+                    string digitalTwinId = twin.Key;
 
                     #region Snippet:DigitalTwinsSampleDeleteTwin
 
-                    await client.DeleteDigitalTwinAsync(twin.Key);
+                    Response deleteDigitalTwinResponse = await client.DeleteDigitalTwinAsync(digitalTwinId);
+                    Console.WriteLine($"Deleted digital twin with Id {digitalTwinId}. Response Status: {deleteDigitalTwinResponse.Status}");
 
                     #endregion Snippet:DigitalTwinsSampleDeleteTwin
 
-                    Console.WriteLine($"Deleted digital twin {twin.Key}");
                 }
                 catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
                 {
@@ -353,8 +343,6 @@ public async Task ConnectTwinsTogetherAsync()
                 // We deserialize as BasicRelationship to get the entire custom relationship (custom relationship properties).
                 IEnumerable<BasicRelationship> relationships = JsonSerializer.Deserialize<IEnumerable<BasicRelationship>>(relationshipSet.Value);
 
-                #region Snippet:DigitalTwinsSampleCreateRelationship
-
                 // From loaded relationships, get the source Id and Id from each one,
                 // and create it with full relationship payload
                 foreach (BasicRelationship relationship in relationships)
@@ -375,8 +363,6 @@ await client.CreateRelationshipAsync(
                         Console.WriteLine($"Relationship {relationship.Id} already exists: {ex.Message}");
                     }
                 }
-
-                #endregion Snippet:DigitalTwinsSampleCreateRelationship
             }
         }
 
@@ -421,10 +407,9 @@ public async Task CreateEventRoute()
                 };
 
                 Response createEventRouteResponse = await client.CreateEventRouteAsync(_eventRouteId, eventRoute);
+                Console.WriteLine($"Created event route with Id {_eventRouteId}. Response status: {createEventRouteResponse.Status}");
 
                 #endregion Snippet:DigitalTwinsSampleCreateEventRoute
-
-                Console.WriteLine($"Created event route: {_eventRouteId} Response status: {createEventRouteResponse.Status}");
             }
             catch (Exception ex)
             {
@@ -443,10 +428,9 @@ public async Task DeleteEventRoute()
                 #region Snippet:DigitalTwinsSampleDeleteEventRoute
 
                 Response response = await client.DeleteEventRouteAsync(_eventRouteId);
+                Console.WriteLine($"Deleted event route with Id {_eventRouteId}. Response status: {response.Status}");
 
                 #endregion Snippet:DigitalTwinsSampleDeleteEventRoute
-
-                Console.WriteLine($"Successfully deleted event route: {_eventRouteId}, status: {response.Status}");
             }
             catch (Exception ex)
             {

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/ModelLifecycleSamples.cs

@@ -26,15 +26,15 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
             // For the purpose of this example we will create temporary models using random model Ids and then decommission a model.
             // We have to make sure these model Ids are unique within the DT instance.
 
-            string newComponentModelId = await GetUniqueModelIdAsync(SamplesConstants.TemporaryComponentModelPrefix, client);
+            string componentModelId = await GetUniqueModelIdAsync(SamplesConstants.TemporaryComponentModelPrefix, client);
             string sampleModelId = await GetUniqueModelIdAsync(SamplesConstants.TemporaryModelPrefix, client);
 
             string newComponentModelPayload = SamplesConstants.TemporaryComponentModelPayload
-                .Replace(SamplesConstants.ComponentId, newComponentModelId);
+                .Replace(SamplesConstants.ComponentId, componentModelId);
 
             string newModelPayload = SamplesConstants.TemporaryModelWithComponentPayload
                 .Replace(SamplesConstants.ModelId, sampleModelId)
-                .Replace(SamplesConstants.ComponentId, newComponentModelId);
+                .Replace(SamplesConstants.ComponentId, componentModelId);
 
             // Then we create the model
 
@@ -43,7 +43,7 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
                 #region Snippet:DigitalTwinsSampleCreateModels
 
                 Response<IReadOnlyList<ModelData>> response = await client.CreateModelsAsync(new[] { newComponentModelPayload, newModelPayload });
-                Console.WriteLine($"Successfully created a model with Id: {newComponentModelId}, {sampleModelId}, status: {response.GetRawResponse().Status}");
+                Console.WriteLine($"Created models with Ids {componentModelId} and {sampleModelId}. Response status: {response.GetRawResponse().Status}");
 
                 #endregion Snippet:DigitalTwinsSampleCreateModels
             }
@@ -62,10 +62,10 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
                 #region Snippet:DigitalTwinsSampleGetModel
 
                 Response<ModelData> sampleModel = await client.GetModelAsync(sampleModelId);
+                Console.WriteLine($"Retrieved model with Id {sampleModelId}. Response status: {sampleModel.GetRawResponse().Status}");
 
                 #endregion Snippet:DigitalTwinsSampleGetModel
 
-                Console.WriteLine($"{sampleModel.Value.Id} has decommission status of {sampleModel.Value.Decommissioned}");
             }
             catch (Exception ex)
             {
@@ -78,12 +78,12 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
 
             try
             {
-                await client.DecommissionModelAsync(sampleModelId);
-                Console.WriteLine($"Successfully decommissioned model {sampleModelId}");
+                Response decommissionModelResponse = await client.DecommissionModelAsync(sampleModelId);
+                Console.WriteLine($"Decommissioned model with Id {sampleModelId}. Response status: {decommissionModelResponse.Status}");
             }
             catch (RequestFailedException ex)
             {
-                FatalError($"Failed to decommision model {sampleModelId} due to:\n{ex}");
+                FatalError($"Failed to decommision model with Id {sampleModelId} due to:\n{ex}");
             }
 
             #endregion Snippet:DigitalTwinsSampleDecommisionModel
@@ -94,13 +94,12 @@ public async Task RunSamplesAsync(DigitalTwinsClient client)
 
             try
             {
-                await client.DeleteModelAsync(sampleModelId);
-
-                Console.WriteLine($"Deleted model {sampleModelId}");
+                Response deleteModelResponse = await client.DeleteModelAsync(sampleModelId);
+                Console.WriteLine($"Deleted model with Id {sampleModelId}. Response status: {deleteModelResponse.Status}");
             }
             catch (Exception ex)
             {
-                FatalError($"Failed to delete model {sampleModelId} due to:\n{ex}");
+                FatalError($"Failed to delete model with Id {sampleModelId} due to:\n{ex}");
             }
 
             #endregion Snippet:DigitalTwinsSampleDeleteModel

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/Program.cs

@@ -52,6 +52,9 @@ public static async Task Main(string[] args)
 
             var publishTelemetrySamples = new PublishTelemetrySamples();
             await publishTelemetrySamples.RunSamplesAsync(dtClient);
+
+            var relationshipSamples = new RelationshipSamples();
+            await relationshipSamples.RunSamplesAsync(dtClient);
         }
 
         /// <summary>

sdk/digitaltwins/Azure.DigitalTwins.Core/samples/DigitalTwinsClientSample/PublishTelemetrySamples.cs

@@ -56,7 +56,7 @@ await client
 
                 // construct your json telemetry payload by hand.
                 Response publishTelemetryResponse = await client.PublishTelemetryAsync(twinId, "{\"Telemetry1\": 5}");
-                Console.WriteLine($"Successfully published telemetry message, status: {publishTelemetryResponse.Status}");
+                Console.WriteLine($"Published telemetry message to twin with Id {twinId}. Response status: {publishTelemetryResponse.Status}");
 
                 #endregion Snippet:DigitalTwinsSamplePublishTelemetry
 
@@ -71,7 +71,7 @@ await client
                     twinId,
                     "Component1",
                     JsonSerializer.Serialize(telemetryPayload));
-                Console.WriteLine($"Successfully published component telemetry message, status: {publishTelemetryToComponentResponse.Status}");
+                Console.WriteLine($"Published component telemetry message to twin with Id {twinId}. Response status: {publishTelemetryToComponentResponse.Status}");
 
                 #endregion Snippet:DigitalTwinsSamplePublishComponentTelemetry
             }