Get started with device management (.NET)

Article
12/23/2022

This article shows you how to create:

SimulateManagedDevice: a simulated device app with a direct method that reboots the device and reports the last reboot time. Direct methods are invoked from the cloud.
TriggerReboot: a .NET console app that calls the direct method in the simulated device app through your IoT hub. It displays the response and updated reported properties.

Prerequisites

Visual Studio.
An IoT Hub. Create one with the CLI or the Azure portal.
A registered device. Register one in the Azure portal.
Make sure that port 8883 is open in your firewall. The device sample in this article uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see Connecting to IoT Hub (MQTT).

Create a device app with a direct method

In this section, you:

Create a .NET console app that responds to a direct method called by the cloud.
Trigger a simulated device reboot.
Use the reported properties to enable device twin queries to identify devices and when they were last rebooted.

To create the simulated device app, follow these steps:

Open Visual Studio and select Create a new project, then find and select the Console App (.NET Framework) project template, then select Next.
In Configure your new project, name the project SimulateManagedDevice, then select Next.
Keep the default .NET Framework version, then select Create.
In Solution Explorer, right-click the new SimulateManagedDevice project, and then select Manage NuGet Packages.
Select Browse, then search for and select Microsoft.Azure.Devices.Client. Select Install.

This step downloads, installs, and adds a reference to the Azure IoT device SDK NuGet package and its dependencies.

Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Add the following fields to the Program class. Replace the {device connection string} placeholder value with the device connection string you saw when you registered a device in the IoT Hub:
```
static string DeviceConnectionString = "{device connection string}";
static DeviceClient Client = null;
```

Add the following to implement the direct method on the device:

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
    // In a production device, you would trigger a reboot 
    //   scheduled to start after this method returns.
    // For this sample, we simulate the reboot by writing to the console
    //   and updating the reported properties.
    try
    {
        Console.WriteLine("Rebooting!");

        // Update device twin with reboot time. 
        TwinCollection reportedProperties, reboot, lastReboot;
        lastReboot = new TwinCollection();
        reboot = new TwinCollection();
        reportedProperties = new TwinCollection();
        lastReboot["lastReboot"] = DateTime.Now;
        reboot["reboot"] = lastReboot;
        reportedProperties["iothubDM"] = reboot;
        Client.UpdateReportedPropertiesAsync(reportedProperties).Wait();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }

    string result = @"{""result"":""Reboot started.""}";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Finally, add the following code to the Main method to open the connection to your IoT hub and initialize the method listener:

try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    // setup callback for "reboot" method
    Client.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
    Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
    Console.ReadLine();

    Console.WriteLine("Exiting...");

    // as a good practice, remove the "reboot" handler
    Client.SetMethodHandlerAsync("reboot", null, null).Wait();
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

In Solution Explorer, right-click your solution, and then select Set StartUp Projects.
For Common Properties > Startup Project, Select Single startup project, and then select the SimulateManagedDevice project. Select OK to save your changes.
Select Build > Build Solution.

Note

To keep things simple, this article does not implement any retry policy. In production code, you should implement retry policies (such as an exponential backoff), as suggested in Transient fault handling.

Get the IoT hub connection string

In this article, you create a backend service that invokes a direct method on a device. To invoke a direct method on a device through IoT Hub, your service needs the service connect permission. By default, every IoT Hub is created with a shared access policy named service that grants this permission.

To get the IoT Hub connection string for the service policy, follow these steps:

In the Azure portal, select Resource groups. Select the resource group where your hub is located, and then select your hub from the list of resources.
On the left-side pane of your IoT hub, select Shared access policies.
From the list of policies, select the service policy.
Copy the Primary connection string and save the value.

For more information about IoT Hub shared access policies and permissions, see Access control and permissions.

Create a service app to trigger a reboot

In this section, you create a .NET console app, using C#, that initiates a remote reboot on a device using a direct method. The app uses device twin queries to discover the last reboot time for that device.

Open Visual Studio and select Create a new project.
In Create a new project, find and select the Console App (.NET Framework) project template, and then select Next.
In Configure your new project, name the project TriggerReboot, then select Next.
Accept the default version of the .NET Framework, then select Create to create the project.
In Solution Explorer, right-click the TriggerReboot project, and then select Manage NuGet Packages.
Select Browse, then search for and select Microsoft.Azure.Devices. Select Install to install the Microsoft.Azure.Devices package.

This step downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Add the following fields to the Program class. Replace the {iot hub connection string} placeholder value with the IoT Hub connection string you copied previously in Get the IoT hub connection string.
```
static RegistryManager registryManager;
static string connString = "{iot hub connection string}";
static ServiceClient client;
static string targetDevice = "myDeviceId";
```

Add the following method to the Program class. This code gets the device twin for the rebooting device and outputs the reported properties.

public static async Task QueryTwinRebootReported()
{
    Twin twin = await registryManager.GetTwinAsync(targetDevice);
    Console.WriteLine(twin.Properties.Reported.ToJson());
}

Add the following method to the Program class. This code initiates the reboot on the device using a direct method.

public static async Task StartReboot()
{
    client = ServiceClient.CreateFromConnectionString(connString);
    CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
    method.ResponseTimeout = TimeSpan.FromSeconds(30);

    CloudToDeviceMethodResult result = await 
      client.InvokeDeviceMethodAsync(targetDevice, method);

    Console.WriteLine("Invoked firmware update on device.");
}

Finally, add the following lines to the Main method:

registryManager = RegistryManager.CreateFromConnectionString(connString);
StartReboot().Wait();
QueryTwinRebootReported().Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Select Build > Build Solution.

Note

This article performs only a single query for the device's reported properties. In production code, we recommend polling to detect changes in the reported properties.

Run the apps

You're now ready to run the apps.

To run the .NET device app SimulateManagedDevice, in Solution Explorer, right-click the SimulateManagedDevice project, select Debug, and then select Start new instance. The app should start listening for method calls from your IoT hub.
After that the device is connected and waiting for method invocations, right-click the TriggerReboot project, select Debug, and then select Start new instance.

You should see "Rebooting!" written in the SimulatedManagedDevice console and the reported properties of the device, which include the last reboot time, written in the TriggerReboot console.

Customize and extend the device management actions

Your IoT solutions can expand the defined set of device management patterns or enable custom patterns by using the device twin and cloud-to-device method primitives. Other examples of device management actions include factory reset, firmware update, software update, power management, network and connectivity management, and data encryption.

Device maintenance windows

Typically, you configure devices to perform actions at a time that minimizes interruptions and downtime. Device maintenance windows are a commonly used pattern to define the time when a device should update its configuration. Your back-end solutions can use the desired properties of the device twin to define and activate a policy on your device that enables a maintenance window. When a device receives the maintenance window policy, it can use the reported property of the device twin to report the status of the policy. The back-end app can then use device twin queries to attest to compliance of devices and each policy.

Next steps

In this article, you used a direct method to trigger a remote reboot on a device. You used the reported properties to report the last reboot time from the device, and queried the device twin to discover the last reboot time of the device from the cloud.

To continue getting started with IoT Hub and device management patterns such as remote over the air firmware update, see How to do a firmware update.

To learn how to extend your IoT solution and schedule method calls on multiple devices, see Schedule and broadcast jobs.