LongHaul - Updated setup file and migration guide (#3305)

* LongHaul - Updated setup file and migration guide

* cr comments

* cr comments

* Update Parameters.cs

* added doc comments to explain TryGetPayload() behavior

* minor

* removed getPayloadAsString in methodrequest

* test fix

Author: tmahmood-microsoft

SDK v2 migration guide.md

@@ -101,7 +101,7 @@ The v2 strategy can be grouped into 3 categories.
     - Review the `IsTransient` property to determine if an exception is transient.
     - Review the `ErrorCode` property for specific, structured error details.
     - For the service client only, the `StatusCode` property is the HTTP status response.
-    - The exception message is meant for human readable expanation.
+    - The exception message is meant for human readable explanation.
     - Inner exceptions may offer more insight and are worth logging out.
     - `TrackingId` is for uniquely identifying specific operations and are useful in sharing with IoT hub support to assist them in more quickly identifying errors that may have been logged by the service.
   - `ProvisioningClientException` for provisioning device client and `ProvisioningServiceException` for provisioning service client for exceptions arising from communication attempts with DPS.
@@ -198,6 +198,7 @@ Find a client you currently use below, read the table of API name changes and us
 | `Message.CreationTimeUtc` | `TelemetryMessage.CreatedOnUtc`, `IncomingMessage.CreatedOnUtc` | Conforming to the naming guidelines by the Azure SDK team, where DateTime/Offset types have an "On" suffix (and "Utc" suffix when explicitly in UTC).³ |
 | `Message.EnqueuedTimeUtc` | `TelemetryMessage.EnqueuedtimeUtc`, `IncomingMessage.EnqueuedTimeUtc` | See³ |
 | `Message.ExpiryTimeUtc` | `TelemetryMessage.ExpiresOnUtc`, `IncomingMessage.ExpiresOnUtc` | See³ |
+| `Message.GetBytes` | `IncomingMessage.GetPayloadAsBytes` | More descriptive name. |
 | `DeviceClient.SetRetryPolicy(...)` | `IotHubClientOptions.RetryPolicy` | Should be specified at initialization time, and putting it in the client options object reduces the client API surface. |
 | `ExponentialBackOff` | `IotHubClientExponentialBackOffRetryPolicy` | Clarify it is a retry policy. |
 | `MethodRequest` | `DirectMethodRequest` | See⁴ |

e2e/LongHaul/device/IotHub.cs

@@ -456,7 +456,7 @@ private async void ConnectionStatusChangesHandlerAsync(ConnectionStatusInfo conn
 
         private Task<DirectMethodResponse> DirectMethodCallback(DirectMethodRequest methodRequest)
         {
-            _logger.Trace($"Received direct method [{methodRequest.MethodName}] with payload [{methodRequest.GetPayloadAsJsonString()}].", TraceSeverity.Information);
+            _logger.Trace($"Received direct method [{methodRequest.MethodName}] with payload [{Encoding.UTF8.GetString(methodRequest.GetPayloadAsBytes())}].", TraceSeverity.Information);
 
             switch (methodRequest.MethodName)
             {

e2e/LongHaul/module/IotHub.cs

@@ -3,6 +3,7 @@
 
 using System.Collections.Concurrent;
 using System.Diagnostics;
+using System.Text;
 using Mash.Logging;
 using Microsoft.Azure.Devices.Client;
 using static Microsoft.Azure.Devices.LongHaul.Module.LoggingConstants;
@@ -41,11 +42,12 @@ internal sealed class IotHub : IAsyncDisposable
         public IotHub(Logger logger, Parameters parameters)
         {
             _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-            _moduleConnectionString = parameters.ConnectionString;
+            _moduleConnectionString = parameters.GatewayHostName == null ? parameters.DeviceModuleConnectionString : parameters.EdgeModuleConnectionString;
             _clientOptions = new IotHubClientOptions(parameters.GetTransportSettings())
             {
                 PayloadConvention = parameters.GetPayloadConvention(),
                 SdkAssignsMessageId = SdkAssignsMessageId.WhenUnset,
+                GatewayHostName = parameters.GatewayHostName,
             };
             _moduleClient = null;
         }
@@ -357,7 +359,7 @@ private async void ConnectionStatusChangesHandlerAsync(ConnectionStatusInfo conn
 
         private Task<DirectMethodResponse> DirectMethodCallback(DirectMethodRequest methodRequest)
         {
-            _logger.Trace($"Received direct method [{methodRequest.MethodName}] with payload [{methodRequest.GetPayloadAsJsonString()}].", TraceSeverity.Information);
+            _logger.Trace($"Received direct method [{methodRequest.MethodName}] with payload [{Encoding.UTF8.GetString(methodRequest.GetPayloadAsBytes())}].", TraceSeverity.Information);
 
             switch (methodRequest.MethodName)
             {

e2e/LongHaul/module/Parameters.cs

@@ -22,10 +22,17 @@ internal class Parameters
     {
         [Option(
             'c',
-            "ConnectionString",
+            "DeviceModuleConnectionString",
             Required = false,
-            HelpText = "The connection string for the module to simulate.")]
-        public string ConnectionString { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_LONG_HAUL_MODULE_CONNECTION_STRING");
+            HelpText = "The connection string for the Device module to simulate.")]
+        public string DeviceModuleConnectionString { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_LONG_HAUL_MODULE_CONNECTION_STRING");
+
+        [Option(
+            'e',
+            "EdgeModuleConnectionString",
+            Required = false,
+            HelpText = "The connection string for the Edge module to simulate.")]
+        public string EdgeModuleConnectionString { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_LONG_HAUL_EDGE_MODULE_CONNECTION_STRING");
 
         [Option(
             'i',
@@ -34,6 +41,13 @@ internal class Parameters
             HelpText = "The instrumentation key string for application insights.")]
         public string InstrumentationKey { get; set; } = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_INSTRUMENTATION_KEY");
 
+        [Option(
+            'g',
+            "GatewayHostName",
+            Required = false,
+            HelpText = "The gateway edge device to connect to; if defined, this app will use the EdgeModuleConnectionString, otherwise it uses the DeviceModuleConnectionString.")]
+        public string GatewayHostName { get; set; }
+
         [Option(
             't',
             "Transport",

e2e/LongHaul/module/Program.cs

@@ -114,7 +114,7 @@ await Task
 
         private static Logger InitializeLogging(Parameters parameters)
         {
-            var helper = new IotHubConnectionStringHelper(parameters.ConnectionString);
+            var helper = new IotHubConnectionStringHelper(parameters.GatewayHostName == null ? parameters.DeviceModuleConnectionString : parameters.EdgeModuleConnectionString);
             var logBuilder = new LoggingBuilder
             {
                 AppContext =

e2e/LongHaul/prerequisites/LongHaulSetup.ps1

@@ -228,9 +228,13 @@ $iothubownerSasPrimaryKey = az iot hub policy show --hub-name $iotHubName --name
 ##################################################################################################################################
 
 $longhaulDeviceId = "LongHaulDevice1"
-$longhaulModuleId = "LongHaulModule1"
+$longhaulDeviceModuleId = "LongHaulDeviceModule1"
+$longhaulEdgeDeviceId = "LongHaulEdgeDevice1"
+$longhaulEdgeModuleId = "LongHaulEdgeModule1"
 $longhaulDevice = az iot hub device-identity list -g $ResourceGroup --hub-name $iotHubName --query "[?deviceId=='$longhaulDeviceId'].deviceId" --output tsv
-$longhaulModule = az iot hub module-identity list -g $ResourceGroup --hub-name $iotHubName --query "[?moduleId=='$longhaulModuleId'].moduleId" --output tsv
+$longhaulDeviceModule = az iot hub module-identity list -g $ResourceGroup --hub-name $iotHubName --query "[?moduleId=='$longhaulDeviceModuleId'].moduleId" --output tsv
+$longhaulEdgeDevice = az iot hub device-identity list -g $ResourceGroup --hub-name $iotHubName --query "[?deviceId=='$longhaulEdgeDeviceId'].deviceId" --output tsv
+$longhaulEdgeModule = az iot hub module-identity list -g $ResourceGroup --hub-name $iotHubName --device-id $longhaulEdgeDeviceId --query "[?moduleId=='$longhaulEdgeModuleId'].moduleId" --output tsv
 
 
 if (-not $longhaulDevice)
@@ -239,14 +243,27 @@ if (-not $longhaulDevice)
     az iot hub device-identity create -g $ResourceGroup --hub-name $iotHubName --device-id $longhaulDeviceId --am shared_private_key
 }
 
-if (-not $longhaulModule)
+if (-not $longhaulDeviceModule)
 {
-    Write-Host "`nCreating SAK authenticated module $longhaulModuleId on IoT hub."
-    az iot hub module-identity create -g $ResourceGroup --hub-name $iotHubName --device-id $longhaulDeviceId --module-id $longhaulModuleId --am shared_private_key
+    Write-Host "`nCreating SAK authenticated module $longhaulDeviceModuleId on IoT hub."
+    az iot hub module-identity create -g $ResourceGroup --hub-name $iotHubName --device-id $longhaulDeviceId --module-id $longhaulDeviceModuleId --am shared_private_key
+}
+
+if (-not $longhaulEdgeDevice)
+{
+    Write-Host "`nCreating SAK authenticated edge device $longhaulEdgeDeviceId on Edge hub."
+    az iot edge devices create -g $ResourceGroup --hub-name $iotHubName --device id=$longhaulEdgeDeviceId
+}
+
+if (-not $longhaulEdgeModule)
+{
+    Write-Host "`nCreating SAK authenticated edge module $longhaulEdgeModuleId on Edge hub."
+    az iot hub module-identity create -g $ResourceGroup --hub-name $iotHubName --device-id $longhaulEdgeDeviceId --module-id $longhaulEdgeModuleId
 }
 
 $longhaulDeviceConnectionString = az iot hub device-identity connection-string show --device-id $longhaulDeviceId --hub-name $iotHubName --resource-group $ResourceGroup --output tsv
-$longhaulModuleConnectionString = az iot hub module-identity connection-string show --device-id $longhaulDeviceId --module-id $longhaulModuleId --hub-name $iotHubName --resource-group $ResourceGroup --output tsv
+$longhaulDeviceModuleConnectionString = az iot hub module-identity connection-string show --device-id $longhaulDeviceId --module-id $longhaulDeviceModuleId --hub-name $iotHubName --resource-group $ResourceGroup --output tsv
+$longhaulEdgeModuleConnectionString = az iot hub module-identity connection-string show --device-id $longhaulEdgeDeviceId --module-id $longhaulEdgeModuleId --hub-name $iotHubName --resource-group $ResourceGroup --output tsv
 
 ############################################################################################################################
 # Store all secrets in a KeyVault - Values will be pulled down from here to configure environment variables.
@@ -255,7 +272,8 @@ $longhaulModuleConnectionString = az iot hub module-identity connection-string s
 $keyvaultKvps = @{
     # Environment variables for IoT Hub E2E tests
     "IOTHUB-LONG-HAUL-DEVICE-CONNECTION-STRING" = $longhaulDeviceConnectionString;
-    "IOTHUB-LONG-HAUL-MODULE-CONNECTION-STRING" = $longhaulModuleConnectionString;
+    "IOTHUB-LONG-HAUL-DEVICE-MODULE-CONNECTION-STRING" = $longhaulDeviceModuleConnectionString;
+    "IOTHUB-LONG-HAUL-EDGE-MODULE-CONNECTION-STRING" = $longhaulEdgeModuleConnectionString;
     "APPLICATION-INSIGHTS-INSTRUMENTATION-KEY" = $instrumentationKey;
     "STORAGE-ACCOUNT-CONNECTION-STRING" = $storageAccountConnectionString;
     "IOTHUB-CONNECTION-STRING" = $iotHubConnectionString;

iothub/device/samples/getting started/EdgeModuleMethodSample/EdgeModuleMethodSample.cs

@@ -86,7 +86,7 @@ private void ConnectionStatusChangeHandler(ConnectionStatusInfo connectionInfo)
         private Task<DirectMethodResponse> WriteToConsoleAsync(DirectMethodRequest directMethodRequest)
         {
             Console.WriteLine($"\t *** {directMethodRequest.MethodName} was called.");
-            Console.WriteLine($"\t{directMethodRequest.GetPayloadAsJsonString()}\n");
+            Console.WriteLine($"\t{Encoding.UTF8.GetString(directMethodRequest.GetPayloadAsBytes())}\n");
 
             var directMethodResponse = new DirectMethodResponse(200);
 

iothub/device/samples/getting started/MethodSample/MethodSample.cs

@@ -84,7 +84,7 @@ private void ConnectionStatusChangeHandler(ConnectionStatusInfo connectionInfo)
         private Task<DirectMethodResponse> WriteToConsoleAsync(DirectMethodRequest directMethodRequest)
         {
             Console.WriteLine($"\t *** {directMethodRequest.MethodName} was called.");
-            Console.WriteLine($"\t{directMethodRequest.GetPayloadAsJsonString()}\n");
+            Console.WriteLine($"\t{Encoding.UTF8.GetString(directMethodRequest.GetPayloadAsBytes())}\n");
 
             var directMethodResponse = new DirectMethodResponse(200);
 

iothub/device/samples/getting started/SimulatedDevice/Program.cs

@@ -5,6 +5,7 @@
 // For samples see: https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples
 
 using System;
+using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 using CommandLine;
@@ -63,7 +64,7 @@ private static async Task Main(string[] args)
         }
         private static Task<DirectMethodResponse> DirectMethodCallback(DirectMethodRequest methodRequest)
         {
-            Console.WriteLine($"Received direct method [{methodRequest.MethodName}] with payload [{methodRequest.GetPayloadAsJsonString()}].");
+            Console.WriteLine($"Received direct method [{methodRequest.MethodName}] with payload [{Encoding.UTF8.GetString(methodRequest.GetPayloadAsBytes())}].");
 
             switch (methodRequest.MethodName)
             {

iothub/device/src/DirectMethod/DirectMethodRequest.cs

@@ -111,10 +111,38 @@ public DirectMethodRequest(string methodName)
         /// <summary>
         /// The direct method request payload, deserialized to the specified type.
         /// </summary>
+        /// <remarks>
+        /// Use this method when the payload type is known and it can be deserialized using the configured
+        /// <see cref="PayloadConvention"/>. If it is not JSON or the type is not known, use <see cref="GetPayloadAsBytes"/>.
+        /// </remarks>
         /// <typeparam name="T">The type to deserialize the direct method request payload to.</typeparam>
         /// <param name="payload">When this method returns true, this contains the value of the direct method request payload.
         /// When this method returns false, this contains the default value of the type <c>T</c> passed in.</param>
         /// <returns><c>true</c> if the direct method request payload can be deserialized to type <c>T</c>; otherwise, <c>false</c>.</returns>
+        /// <example>
+        /// <code language="csharp">
+        /// await client.SetDirectMethodCallbackAsync((directMethodRequest) =>
+        /// {
+        ///     if (directMethodRequest.TryGetPayload(out MyCustomType customTypePayload))
+        ///     {
+        ///         // do work
+        ///         // ...
+        ///         
+        ///         // Acknowlege the direct method call with the status code 200.  
+        ///         return Task.FromResult(new DirectMethodResponse(200));
+        ///     }
+        ///     else
+        ///     {
+        ///         // Acknowlege the direct method call the status code 400.
+        ///         return Task.FromResult(new DirectMethodResponse(400));
+        ///     }
+        ///     
+        ///     
+        ///     // ...
+        /// },
+        /// cancellationToken);
+        /// </code>
+        /// </example>
         public bool TryGetPayload<T>(out T payload)
         {
             payload = default;
@@ -129,29 +157,36 @@ public bool TryGetPayload<T>(out T payload)
                 // In case the value cannot be converted using the serializer,
                 // then return false with the default value of the type <T> passed in.
                 if (Logging.IsEnabled)
-                    Logging.Error(this, ex, nameof(TryGetPayload));
+                    Logging.Error(this, $"Unable to convert payload to {typeof(T)} due to {ex}", nameof(TryGetPayload));
             }
 
             return false;
         }
 
-        /// <summary>
-        /// The command payload as a JSON string, if applicable.
-        /// </summary>
-        public string GetPayloadAsJsonString()
-        {
-            return Payload == null || Payload.Length == 0
-                ? null
-                : DefaultPayloadConvention.Encoding.GetString(Payload);
-        }
-
         /// <summary>
         /// Get the raw payload bytes.
         /// </summary>
+        /// <remarks>
+        /// Use this method when the payload is not JSON or the type is not known or the type cannot be deserialized
+        /// using the configured <see cref="PayloadConvention"/>. Otherwise, use <see cref="TryGetPayload{T}(out T)"/>.
+        /// </remarks>
         /// <returns>A copy of the raw payload as a byte array.</returns>
+        /// <example>
+        /// <code language="csharp">
+        /// await client.SetDirectMethodCallbackAsync((directMethodRequest) =>
+        /// {
+        ///     byte[] arr = directMethodRequest.GetPayloadAsBytes();
+        ///     // deserialize as needed and do work...
+        ///     
+        ///     // Acknowlege the direct method call with the status code 200. 
+        ///     return Task.FromResult(new DirectMethodResponse(200));
+        /// },
+        /// cancellationToken);
+        /// </code>
+        /// </example>
         public byte[] GetPayloadAsBytes()
         {
-            return (byte[])Payload.Clone();
+            return Payload == null || Payload.Length==0 ? null : (byte[])Payload.Clone();
         }
     }
 }