diff --git a/MIGRATION_v7.0.0.md b/MIGRATION_v7.0.0.md index 86f028b20..eac19ec8f 100644 --- a/MIGRATION_v7.0.0.md +++ b/MIGRATION_v7.0.0.md @@ -4,13 +4,19 @@ This document covers all breaking changes introduced with v7.0.0. If you migrate from v6.X.X to v7.X.X (or above), you will have to handle the following points in your codebase. -## Everything flagged with an `Obsolete` annotation will be removed +### Everything flagged with an 'Obsolete' annotation has been removed -### Synchronous methods +When upgrading to a newer release, you may have noticed a warning indicating you're using an obsolete method. +Indeed, we flagged these changes with an `Obsolete` tag. -So far, a lot of features are available with both synchronous/asynchronous implementation. -In [v7.0.0](https://github.com/Vonage/vonage-dotnet-sdk/releases/tag/v7.0.0), all synchronous methods will be removed. -If you still require to call a Vonage API in a synchronous context, you will have to call the asynchronous version with +Please note that there's always a substitute when we decommission something. + +#### Synchronous methods + +So far, many features are available with both synchronous/asynchronous implementation. +All synchronous methods have been removed in [v7.0.0](https://github.com/Vonage/vonage-dotnet-sdk/releases/tag/v7.0.0). +If you are still requires to call a Vonage API in a synchronous context, you will have to call the asynchronous version +with either `.Result` or `.Wait()` to wait for the result synchronously. ```csharp @@ -23,10 +29,10 @@ await applicationClient.DeleteApplicationAsync(applicationId); applicationClient.DeleteApplicationAsync(applicationId).Wait(); ``` -### SubAccounts features on `AccountClient` +#### SubAccounts features on 'AccountClient' -SubAccounts features have initially been implemented by a contributor on the `AccountClient`, while the product was -still in beta. +SubAccounts features were initially implemented by a contributor on the `AccountClient` while the product was still in +beta. With the GA release, all SubAccounts features are available on the `SubAccountsClient`, which makes previous features obsolete. @@ -38,9 +44,9 @@ var request = GetSubAccountRequest.Parse(subAccountKey); var subAccount = await vonageClient.SubAccountClient.GetSubAccountAsync(request); ``` -### `CreateApplicaitonAsync` on `ApplicationClient` +#### 'CreateApplicaitonAsync' on 'ApplicationClient' -This method contains an obvious typo. +The current method contains a typo. ```csharp // Using v6.X.X @@ -50,10 +56,10 @@ var application = await applicationClient.CreateApplicaitonAsync(request); var application = await applicationClient.CreateApplicationAsync(request); ``` -### `CreateCall` on `VoiceClient` +#### 'CreateCall' on 'VoiceClient' -This method offers 3 different signatures. -Only the one with a `CallCommand` parameter will remain in order to avoid primitive obsession, and rely on a proper +This method offers three different signatures. +Only the one with a `CallCommand` parameter will remain to avoid primitive obsession and rely on a proper ValueObject. ```csharp @@ -67,10 +73,14 @@ var callResponse = voiceClient.CreateCallAsync(callCommand); var callResponse = voiceClient.CreateCallAsync(callCommand); ``` -### Constructors on `Credentials` +#### Constructors on 'Credentials' -Creating a Credentials instance should be done by a factory method or from a `Configuration` instance. -Constructors will be hidden and the object will remain immutable. +Creating a Credentials instance should be done using a factory method or from a `Configuration` instance. +Constructors will be hidden, and the object will remain immutable. + +We highly recommend you to use +our [extension methods](https://developer.vonage.com/en/blog/implicit-configuration-in-net) to dynamically +initialize `Credentials` from your `appsettings.json` file. ```csharp // Using v6.X.X @@ -87,12 +97,13 @@ var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret); var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret); var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret); var credentials = configuration.BuildCredentials(); +// Recommended var credentials = serviceCollection.GetRequiredService(); ``` -### Access to Vonage URLs +#### Access to Vonage URLs -All URLs have been moved to a nested object (`VonageUrls`) to "de-bloat"the `Configuration` class, and allow +All URLs have been moved to a nested object (`VonageUrls`) to "de-bloat" the `Configuration` class and allow multi-region URLs. ```csharp @@ -109,15 +120,15 @@ var url = configuration.VonageUrls.Video; var url = configuration.VonageUrls.Get(VonageUrls.Region.US); ``` -## Add new timeouts on Voice Webhooks in Application API +### Add new timeouts on Voice Webhooks in Application API -Adding new timeouts requested (`connection_timeout`, `socket_timeout`) on Voice WebHooks. +Adding new timeouts requested (`connection_timeout`, `socket_timeout`) on Voice Webhooks. Creating a specific structure, different from other webhooks, required to break the `Capability` inheritance. -## Rename settings key from `appSettings` to `vonage` +### Rename settings key from 'appSettings' to 'vonage' -In order to make the settings more explicit and reduce chances of conflict with other libraries, the base key needs to -be updated. +In order to make the settings more explicit and reduce chances of conflict with other libraries, the base key has been +updated. Using v6.X.X @@ -139,17 +150,17 @@ Using v7.X.X and above } ``` -## Make StartTime nullable on Answered Webhook +### Make StartTime nullable on Answered Webhook As defined in the [specs](https://developer.vonage.com/en/voice/voice-api/webhook-reference#answered), the `StartTime` -is actually nullable. +is now nullable. -## Remove `EventUrl` and `EventMethod` from `ConversationAction` +### Remove 'EventUrl' and 'EventMethod' from 'ConversationAction' As defined in the [specs](https://developer.vonage.com/en/voice/voice-api/ncco-reference#conversation), -the `Conversation` action doesn't have an `EventUrl` or an `EventMethod`. +the `Conversation` action doesn't have an `EventUrl` or an `EventMethod`. -## Make `From` mandatory in VerifyV2 WhatsApp workflow +### Make 'From' mandatory in VerifyV2 WhatsApp workflow The `From` property used to be optional - it is now mandatory. @@ -160,4 +171,4 @@ var workflow = WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber); // Using v7.X.X and above var workflow = WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber); -``` +``` \ No newline at end of file