Update SDK v2 migration guide.md (#2889)

* Update SDK v2 migration guide.md

SDK v2 migration guide.md

@@ -13,16 +13,58 @@ are outlines of the notable breaking changes as well as a mapping from version 1
    - [IoT hub service client](#iot-hub-service-client)
    - [Device Provisioning Service (DPS) device client](#dps-device-client)
    - [DPS service client](#dps-service-client)
-   - [Security provider client](#authentication-provider-client)
+   - [Security provider client](#security-provider-client)
  - [Frequently asked questions](#frequently-asked-questions)
 
 ## Why the version 1 SDK is being replaced
 
 There are a number of reasons why the Azure IoT SDK team chose to do a major version revision. Here are a few of the more important reasons:
-  - Removing or upgrading several NuGet dependencies (TODO: list).
-  - Consolidate IoT hub service clients and rename to reflect the items or operations they support.
-    - Many existing client classes (RegistryManager, ServiceClient, etc.) were confusingly named and contained methods that weren't always consistent with the client's assumed responsibilities.
-  - Many existing clients had a mix of standard constructors (`new DeviceClient(...)`) and static builder methods (`DeviceClient.CreateFromConnectionString(...)`) that caused some confusion among users. The factory methods have been removed and the addition of constructors in clients enables unit testing.
+
+### Creating, removing, or upgrading several NuGet dependencies.
+
+- Created
+  - Microsoft.Azure.Devices.Authentication
+- Upgraded
+  - Microsoft.Azure.Devices (IoT hub service)
+  - Microsoft.Azure.Devices.Client (IoT hub device)
+  - Microsoft.Azure.Devices.Provisioning.Client
+  - Microsoft.Azure.Devices.Provisioning.Service
+- Removed
+  - Microsoft.Azure.Devices.Shared
+  - Microsoft.Azure.Devices.Provisioning.Transport.Amqp
+  - Microsoft.Azure.Devices.Provisioning.Transport.Http
+  - Microsoft.Azure.Devices.Provisioning.Transport.Mqtt
+  - Microsoft.Azure.Devices.Provisioning.Security.Tpm
+
+### Consolidating IoT hub service clients and renaming to reflect the items or operations they support.
+
+Many existing client classes (RegistryManager, ServiceClient, etc.) were confusingly named and contained methods that weren't always consistent with the client's assumed responsibilities.
+
+### Client constructors and mocking
+
+Many existing clients had a mix of standard constructors (`new RegistryManager(...)`) and static builder methods (`DeviceClient.CreateFromConnectionString(...)`) that caused some confusion among users. The factory methods have been removed and the addition of constructors in clients also enables unit test mocking.
+
+### Exception handling
+
+Exception handling in the v1 SDK required a wide variety of exception types to be caught. Exception types have been consolidated.
+
+- Parameter validation may throw the following exceptions.
+  - `ArgumentException` for basic parameter validation.
+    - Also, `ArgumentNullException` and `ArgumentOutOfRangeException` inherit from it and provide more specific feedback.
+  - `FormatException` when a string parameter format does not match what is expected (e.g., connection string with embedded key/value pairs).
+  - `InvalidOperationException`
+    - For example, when calling device client operations before explicility calling `IotHubDeviceClient.OpenAsync()` first.
+    - When some runtime validated user input is invalid in some other way, for example, importing or exporting devices where there is a null value in the list.
+- `OperationCanceledException` when a cancellation token is signaled.
+- When an operation fails:
+  - `IotHubClientException` for device client and `IotHubServiceException` for service client for any exceptions arising from communication attempts with IoT hub.
+    - Based on `IotHubServiceErrorCode`, we determine if an exception is transient. Check error code for a specific error in details.
+  - `DeviceProvisioningClientException` for provisioning client and `DeviceProvisioningServiceException` for provisioning service client for exceptions arising from communication attempts with DPS.
+
+### Connection monitoring and client lifetime
+
+- Caching the latest connection status information on device client, so the client app does not have to do it.
+- `RecommendedAction` enum provided in connection status handling based on connection status to assist in know what action the client app is recommended to take.
 
 ## What will happen to the version 1 SDK
 
@@ -99,7 +141,7 @@ but users are still encouraged to migrate to version 2 when they have the chance
 
 | Version 1 API | Equivalent version 2 API |
 |:---|:---|
-| `RegistryManager` | `IotHubServiceClient`, subclients `Devices`, `Twins`, `Configurations`, etc. |
+| `RegistryManager` | `IotHubServiceClient`, subclients: `Devices`, `Twins`, `Configurations`, etc. |
 | `RegistryManager.AddDeviceAsync(Device, ...)` | `IotHubServiceClient.Devices.CreateAsync(Device, ...)` |
 | `RegistryManager.AddDevices2Async(...)` | `IotHubServiceClient.Devices.CreateAsync(IEnumerable<Device>,...)` |
 | `RegistryManager.RemoveDeviceAsync(...)` | `IotHubServiceClient.Devices.DeleteAsync(...)` |
@@ -265,7 +307,7 @@ but users are still encouraged to migrate to version 2 when they have the chance
 - Query methods (like for individual and group enrollments) now take a query string (and optionally a page size parameter), and the `Query` result no longer requires disposing.
 - ETag fields on the classes `IndividualEnrollment`, `EnrollmentGroup`, and `DeviceRegistrationState` are now taken as the `Azure.ETag` type instead of strings.
 
-### Security provider clients
+### Security provider client
 
 Breaking changes:
 
@@ -334,4 +376,4 @@ Question:
 > Is the version 2 library backwards compatible?
 
 Answer:
-> No. Please refer to [Semver rules](https://semver.org/) and see above in the [Migration guide](#migration-guide).
+> No. Please refer to [Semver rules](https://semver.org/) and see above in the [Migration guide](#migration-guide).