azure-iot-sdk-python/migration_guide.md

IoTHub Python SDK Migration Guide

This guide details how to update existing code that uses an azure-iot-device V2 release to use a V3 release instead. While the APIs remain mostly the same, there are a few differences you may need to account for in your application, as we have removed some of the implicit behaviors present in V2 in order to provide a more reliable and consistent user experience.

Connecting to IoTHub

One of the primary changes in V3 is the removal of automatic connections when invoking other APIs on the IoTHubDeviceClient and IoTHubModuleClient. You must now make an explicit manual connection before sending or receiving any data.

V2

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")
client.send_message("some message")

V3

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")
client.connect()
client.send_message("some message")

Note that many people using V2 may already have been doing manual connects, as for some time, this has been our recommended practice.

Note also that this change does not affect automatic reconnection attempts in the case of network failure. Once the manual connect has been successful, the client will (under default settings) still attempt to retain that connected state as it did in V2.

Receiving data from IoTHub

Similarly to the above, there is an additional explicit step you must now make when trying to receive data. In addition to setting your handler, you must explicitly start/stop receiving. Note also that the above step of manually connecting must also be done before starting to receive data.

V2

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")

# define behavior for receiving a message
def message_handler(message):
    print("the data in the message received was ")
    print(message.data)
    print("custom properties are")
    print(message.custom_properties)

# set the message handler on the client
client.on_message_received = message_handler

V3

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")

# define behavior for receiving a message
def message_handler(message):
    print("the data in the message received was ")
    print(message.data)
    print("custom properties are")
    print(message.custom_properties)

# set the message handler on the client
client.on_message_received = message_handler

# connect and start receiving messages
client.connect()
client.start_message_receive()

Note that this must be done not just for receiving messages, but receiving any data. Consult the chart below to see which APIs you will need for the type of data you are receiving.

Data Type	Handler name	Start Receive API	Stop Receive API
Messages	.on_message_received	.start_message_receive()	.stop_message_receive()
Method Requests	.on_method_request_received	.start_method_request_receive()	.stop_method_request_receive()
Twin Desired Properties Patches	.on_twin_desired_properties_patch_received	.start_twin_desired_properties_patch_receive()	.stop_twin_desired_properties_patch_receive()

Finally, it should be clarified that the following receive APIs that were deprecated in V2 have been fully removed in V3:

• .receive_message()
• .receive_message_on_input()
• .receive_method_request()
• .receive_twin_desired_properties_patch()

All receives should now be done using the handlers in the table above.

Modified Client Options - IoTHubDeviceClient/IoTHubModuleClient

Some keyword arguments provided at client creation have changed or been removed

V2	V3	Explanation
auto_connect	REMOVED	Initial manual connection now required
ensure_desired_properties	REMOVED	No more implicit twin updates

Shutting down - IoTHubDeviceClient/IoTHubModuleClient

While using the .shutdown() method when you are completely finished with an instance of the client has been a highly recommended practice for some time, some early versions of V2 did not require it. As of V3, in order to ensure a graceful exit, you must make an explicit shutdown.

V2

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")

# ...
#<do things>
# ...

V3

from azure.iot.device import IoTHubDeviceClient

client = IoTHubDeviceClient.create_from_connection_string("<Your Connection String>")

# ...
#<do things>
# ...

client.shutdown()

Shutting down - ProvisioningDeviceClient

As with the IoTHub clients mentioned above, the Provisioning clients now also require shutdown. This was implicit in V2, but now it must be explicit and manual to ensure graceful exit.

V2

from azure.iot.device import ProvisioningDeviceClient

client = ProvisioningDeviceClient.create_from_symmetric_key(
        provisioning_host="<Your provisioning host>",
        registration_id="<Your registration id>",
        id_scope="<Your id scope>",
        symmetric_key="<Your symmetric key">,
    )

registration_result = client.register()

# Shutdown is implicit upon successful registration

V3

from azure.iot.device import ProvisioningDeviceClient

client = ProvisioningDeviceClient.create_from_symmetric_key(
        provisioning_host="<Your provisioning host>",
        registration_id="<Your registration id>",
        id_scope="<Your id scope>",
        symmetric_key="<Your symmetric key">,
    )

registration_result = client.register()

# Manual shutdown for graceful exit
client.shutdown()