Vonage Video Transition Guide for .NET

Transitioning from Opentok-.NET-SDK to vonage-dotnet-sdk

Introduction

Purpose

The goal of this document is to provide a starting point for transitioning from the OpenTok .NET Server SDK to the Vonage .NET Server SDK.

Scope

This document assumes that you are using at least version 3.14.0 or later of the OpenTok .NET SDK.

The Video API was added to the .NET Server SDK in version 6.14.0. You should use the latest version of the Vonage .NET SDK, which can be found on GitHub or NuGet.

Assumptions

This guide is intended to be followed by a professional software engineer. At least a basic level of competency with .NET, common .NET developer tools, build systems and Git (or other version control system) is assumed. You should be comfortable reading and writing .NET code, managing project dependencies, deploying and executing a .NET project. An introduction to the .NET language, platform and associated tooling is well beyond the scope of this document.

Resources

The following links are useful for further reading to accompany this document and for reference to anything not covered in this document:

Vonage

• Vonage Video documentation
• Vonage Video API specification
• Vonage .NET Server SDK Video usage guide
• Vonage .NET Server SDK Video source code
• Vonage .NET Server SDK GitHub repo
• Vonage .NET Server SDK published artifacts on NuGet

TokBox

• OpenTok API REST reference
• OpenTok .NET Server SDK documentation
• OpenTok .NET Server SDK source code
• OpenTok .NET Server SDK GitHub repo
• OpenTok .NET Server SDK published artifacts on NuGet

Planning Your Migration

Before transitioning from OpenTok to Vonage Video, you should consider the scale of the task to set realistic expectations.

Evaluate Impact

The first question to answer is: how much of your application's code depends on the OpenTok SDK? Make a list of all the files in which the SDK is directly used. That is, any .cs file which contains a using OpenTokSDK reference. You can search through the files in your project for the statement using OpenTokSDK using an IDE (Ctrl+Shift+F) or command-line tool to identify the files affected.

Timeline

Take into account the time required to complete the transition. This will depend on your experience with the project and its impact, as well as testing. It is crucial to have a good test suite in place so that you can verify equivalence between the OpenTok and Vonage Video. The time it will take to complete the transition is roughly proportional to the number of places where the OpenTok SDK is used in your code, as well as the variety of features used. Some API calls will be simpler to replace than others.

Versioning

OpenTok and Vonage Video are two different products - This makes a progressive migration impossible.

You should create a temporary branch on your version control system for the transition, so that you can make changes gradually and frequently without breaking the existing project. You can also use the existing project's tests as an oracle for correctness. Ideally, you should only merge the transition branch into the main branch once you have completed the conversion.

Key Changes and Considerations

New Features and Standards

The Vonage Video API has feature parity with OpenTok, and the .NET SDK is actively maintained to be in line with the API specification. Still, there are a few major differences between the OpenTok and Vonage .NET SDK.

One of them is relying on proper data models instead of primitive types. The purpose is to avoid "primitive obsession" by giving more domain context to method signatures.

Another one is the extensive use of Monads, over traditional exceptions, to provide a more functional approach to error handling. While Monads may be a fresh concept for developers, they bring valuable benefits such as transparency and predictability while remaining exception-free. For example, creating a new session will return a Task<Result<CreateSessionResponse>> - a Result<T> represents the result of an operation which may fail, and exposes two possible states: a Success or a Failure. In this particular scenario, the Result will contain a CreateSessionResponse if the operation succeeded, or an IResultFailure if it failed.

Package Update

Firstly, you'll need to install or update the Vonage .NET SDK in your project. You can do that using your IDE integrated NuGet package manager (searching for Vonage), or by running the following command in your terminal: dotnet add package Vonage.

For a gradual migration, you can include both OpenTok and Vonage dependencies in your project, however we strongly recommend that this should be for testing only rather than deployments to production, as the OpenTok SDK tends to use older versions of dependencies which may cause issues at runtime.

Authentication Changes

Authentication in both OpenTok and Vonage .NET Server SDKs are handled for you, so you only need to provide your account credentials once upon initialisation. The difference is that OpenTok requires API key & secret, whilst for the Video API in Vonage .NET SDK, you need to provide an application ID and its private key. Whilst both Vonage and OpenTok use token-based authentication, Vonage's tokens are JWTs whilst OpenTok uses a custom format. Whilst you can provide an API key and secret to the VonageClient just as with OpenTok, this is used for other Vonage APIs, not Video. Therefore, you will need to create or use an existing application.

You can create an application from the Vonage Dashboard. Ensure that your application has the Video capability enabled. Click 'Edit' for an existing application to view its capabilities and credentials. From here, click 'Generate public and private key'. This should only be done once, as every time you do this, the credentials change and so will break the existing key pair. Clicking this will trigger a download of your private key. You should place this file somewhere secure for testing. NEVER SHARE OR EXPOSE YOUR PRIVATE KEY! The private key is effectively the "password" to your application, so should be treated carefully. It is recommended that you add your application id and private key to your settings file or KeyVault. See more here on how to configure the SDK.

For further guidance on setting up an application, see the Getting Started guide.

Usage

See the .NET SDK README for setup instructions.

Instead of this, with OpenTok:

Do the following:

Once you have access to an IVideoClient instance, you can use the Video API.

For more detailed usage instructions, see the .NET Sever SDK video guide.

Method Changes

There are some changes to methods between the OpenTok SDK and the Video API implementation in the Vonage SDKs.

• Any operation will return a Result<T>, indicating whether the operation is a success or a failure. For more details, feel free to take a look at the Monads section.
• Creating a request will force you to rely on a builder (ex: CreateSessionRequest.Build()...) - all builders provide a fluent API to guide you through mandatory parameters, while proposing optional ones, before building the request using .Create().
• Methods used to be available in both synchronous and asynchronous versions. The synchronous versions have been removed, leaving only the asynchronous one. If you still want to run that in a synchronous process, please consider using Task.Wait() or Task.Result on the returned Task object.
• Some methods have been renamed and/or moved, for clarity and/or to better reflect what the method does. These are listed below:

Migration Strategies

Incremental Migration

We would recommend an incremental migration, moving from one use case to another, committing every time you end up in a " stable" state. Of course, it would require both OpenTok and Vonage Video API to temporarily coexist.

Please note that, during such incremental process, your application as a whole would not be fully functional anymore as OpenTok and Vonage Video API are two fully different systems.

You should start by creating a specific 'Video Adapter' that would regroup all current interactions with OpenTok, and then replace one by one the use of OpenTok with Vonage Video API.

Another approach could be to duplicate that 'Video Adapter' into a new 'Vonage Video Adapter', dedicated to that migration, before swapping those two adapters together. See more with the Strangler Fig Pattern

Testing Recommendations

Thorough testing is essential for a smooth transition, both during and after the migration. This includes not only unit tests but also integration and regression testing. It is also worth manually testing your application flow at least once before and after the migration to ensure that your automated tests do what you think they do, or to pick up on any issues that the tests may not have caught. You may even consider creating equivalence tests. The idea is to create a suite which asserts that both the OpenTok and Vonage Video versions of your application do the same thing. These can then be discarded once your transition is complete and the OpenTok version of your application is removed.

Troubleshooting & Support

FAQs

It's explained on the SDK's README.

It's explained on the SDK's README.

Support Channels

For general help and discussion on transitioning to Vonage Video, check out the #video-api channel on our Community Slack, where you can get answers from Vonage staff and fellow users. You can also get in touch with us on X @VonageDev. The primary contact for any issues with the Video API itself is support@api.vonage.com. If you find a bug with the SDK, please file an issue with steps to reproduce on GitHub.