Guia de transição do Vonage Video para .NET

A transição de Opentok-.NET-SDK para vonage-dotnet-sdk

Introdução

Objetivo

O objetivo deste documento é fornecer um ponto de partida para a transição do SDK do servidor OpenTok para .NET para o SDK do servidor Vonage para .NET.

Âmbito

Este documento pressupõe que você esteja usando, no mínimo, a versão 3.14.0 ou posterior à a SDK do OpenTok para .NET.

A Video API foi adicionada ao .NET Server SDK na versão 6.14.0. Você deve usar a versão mais recente do SDK .NET da Vonage, que pode ser encontrada em GitHub ou NuGet.

Suposições

Este guia destina-se a ser seguido por um engenheiro de software profissional. Presume-se que o leitor possua, no mínimo, um nível básico de conhecimento em .NET, nas ferramentas comuns de desenvolvimento .NET, em sistemas de compilação e no Git (ou outro sistema de controle de versão). Você deve estar à vontade para ler e escrever código .NET, gerenciar dependências de projeto, implantar e executar um projeto .NET. Uma introdução à linguagem .NET, à plataforma e às ferramentas associadas está muito além do escopo deste documento.

Recursos

Os links a seguir são úteis para leituras complementares a este documento e como referência para qualquer assunto não abordado nele:

Vonage

• Documentação do Vonage Video
• Especificação da Video API da Vonage
• Guia de uso em vídeo do SDK do servidor .NET da Vonage
• Código-fonte do vídeo do SDK do servidor .NET da Vonage
• Repositório do GitHub do SDK do servidor .NET da Vonage
• Artefatos do SDK do servidor .NET da Vonage publicados no NuGet

TokBox

• Referência da API REST do OpenTok
• Documentação do OpenTok .NET Server SDK
• Código-fonte do OpenTok .NET Server SDK
• Repositório do OpenTok .NET Server SDK no GitHub
• Artefatos do OpenTok .NET Server SDK publicados no NuGet

Planejando sua migração

Antes de fazer a transição do OpenTok para o Vonage Video, você deve levar em conta a magnitude da tarefa para definir expectativas realistas .

Avaliar o impacto

A primeira pergunta a ser respondida é: qual a proporção do código do seu aplicativo que depende do SDK do OpenTok? Faça uma lista de todos os arquivos nos quais o SDK é usado diretamente. Ou seja, qualquer .cs arquivo que contém um using OpenTokSDK referência. Você pode procurar nos arquivos do seu projeto pela instrução using OpenTokSDK usando um IDE (Ctrl+Shift+F) ou uma ferramenta de linha de comando para identificar os arquivos afetados.

Linha do tempo

Leve em consideração o tempo necessário para concluir a transição. Isso dependerá da sua experiência com o projeto e do impacto dele, bem como dos testes. É fundamental contar com um bom conjunto de testes para que você possa verificar a equivalência entre o OpenTok e o Vonage Video. O tempo necessário para concluir a transição é aproximadamente proporcional ao número de locais em que o SDK do OpenTok é usado em seu código, bem como à variedade de recursos utilizados. Algumas chamadas de API serão mais simples de substituir do que outras.

Controle de versões

O OpenTok e o Vonage Video são dois produtos diferentes — isso torna impossível uma migração gradual.

Você deve criar um branch temporário no seu sistema de controle de versão para a transição, de modo a poder fazer alterações gradualmente e com frequência, sem afetar o projeto existente. Você também pode usar os testes do projeto existente como referência para verificar a correção. O ideal é que você só faça a fusão do branch de transição com o branch principal depois de ter concluído a conversão.

Principais mudanças e considerações

Novos recursos e normas

A Video API da Vonage possui paridade de recursos com a OpenTok, e o SDK .NET é mantido ativamente para estar em conformidade com a especificação da API. No entanto, existem algumas diferenças importantes entre o SDK .NET da OpenTok e o da Vonage.

Uma delas é recorrer a modelos de dados adequados, em vez de tipos primitivos. O objetivo é evitar “obsessão primitiva"ao fornecer mais contexto do domínio às assinaturas dos métodos.

Outro aspecto é o uso extensivo de Monads, em vez das exceções tradicionais, para oferecer uma abordagem mais funcional ao tratamento de erros. Embora as monads possam ser um conceito novo para os desenvolvedores, elas trazem benefícios valiosos, como transparência e previsibilidade, sem recorrer a exceções. Por exemplo, a criação de uma nova sessão retornará um Task<Result<CreateSessionResponse>> - a Result<T> representa o resultado de uma operação que pode falhar e apresenta dois estados possíveis: um Success ou um Failure. Nesse cenário específico, o Result conterá um CreateSessionResponse se a operação for bem-sucedida, ou um IResultFailure se isso não der certo.

Atualização do pacote

Primeiramente, você precisará instalar ou atualizar o SDK .NET da Vonage no seu projeto. Você pode fazer isso usando o gerenciador de pacotes NuGet integrado ao seu IDE (pesquisando por Vonage), ou executando o seguinte comando no seu terminal: dotnet add package Vonage.

Para uma migração gradual, você pode incluir as dependências do OpenTok e do Vonage em seu projeto; no entanto, recomendamos enfaticamente que isso seja feito apenas para fins de teste, e não para implantações em produção, já que o SDK do OpenTok tende a usar versões mais antigas das dependências, o que pode causar problemas durante a execução.

Alterações na autenticação

A autenticação, tanto no OpenTok quanto no SDK do servidor .NET da Vonage, é feita automaticamente para você; portanto, basta fornecer as credenciais da sua conta apenas uma vez, na inicialização. A diferença é que o OpenTok exige uma chave e um segredo de API, enquanto que, para a Video API no SDK .NET da Vonage, você precisa fornecer um ID de aplicativo e sua chave privada. Embora tanto a Vonage quanto o OpenTok utilizem autenticação baseada em token, os tokens da Vonage são JWTs enquanto o OpenTok utiliza um formato personalizado. Embora você possa fornecer uma chave de API e um segredo para o VonageClient Assim como no OpenTok, isso é utilizado para outras APIs da Vonage, e não para vídeo. Portanto, você precisará criar uma Application ou usar uma já existente.

Você pode criar um aplicativo a partir do Painel do Vonage. Certifique-se de que seu aplicativo tenha o recurso de vídeo ativado. Clique em “Editar” em uma aplicação existente para visualizar seus recursos e credenciais. A partir daí, clique em “Gerar chave pública e privada”. Isso só deve ser feito uma vez, pois cada vez que você fizer isso, as credenciais serão alteradas, o que invalidará o par de chaves existente. Clicar nessa opção iniciará o download da sua chave privada. Você deve armazenar esse arquivo em um local seguro para fins de teste. NUNCA COMPARTILHE OU DIVULGUE SUA CHAVE PRIVADA! A chave privada é, na verdade, a “senha” do seu aplicativo e, por isso, deve ser tratada com cuidado. Recomenda-se que você adicione o ID do seu aplicativo e a chave privada ao seu arquivo de configurações ou ao KeyVault. Veja mais aqui sobre como configurar o SDK.

Para obter mais orientações sobre como configurar um aplicativo, consulte o guia de introdução.

Uso

Veja O arquivo README do SDK do .NET para obter instruções de configuração.

Em vez disso, com o OpenTok:

var client = new OpenTok(apiKey, apiSecret);

Faça o seguinte:

// In your startup.cs or equivalent, register all Vonage services using your configuration
builder.Services.AddVonageClientScoped(builder.Configuration);

// In any component, inject our IVideoClient (preferred)
public WeatherForecastController(IVideoClient client)
{
    this.client = client;
}

// Or our VonageClient
public WeatherForecastController(VonageClient client)
{
    this.client = client.VideoClient;
}

Assim que você tiver acesso a um IVideoClient Por exemplo, você pode usar o Video API.

Para obter instruções de uso mais detalhadas, consulte o Guia em vídeo do .NET Server SDK.

Alterações no método

Há algumas alterações nos métodos entre o OpenTok O SDK e a implementação da Video API no Vonage SDKs.

• Qualquer operação retornará um Result<T>, indicando se a operação foi bem-sucedida ou falhou. Para mais detalhes, fique à vontade para dar uma olhada no Monads seção.
• A criação de uma solicitação fará com que você precise recorrer a um construtor (ex.: CreateSessionRequest.Build()...) - todos os geradores oferecem uma API intuitiva para orientá-lo sobre os parâmetros obrigatórios, ao mesmo tempo em que sugerem os opcionais, antes de gerar a solicitação usando .Create().
• Os métodos costumavam estar disponíveis nas versões síncrona e assíncrona. As versões síncronas foram removidas, restando apenas a versão assíncrona. Se você ainda quiser executá-la em um processo síncrono, considere usar Task.Wait() ou Task.Result sobre o devolvido Task objeto.
• Alguns métodos foram renomeados e/ou movidos, para maior clareza e/ou para refletir melhor a função do método. Eles estão listados a seguir:

Estratégias de migração

Migração incremental

Recomendamos uma migração gradual, passando de um caso de uso para outro e confirmando as alterações sempre que você chegar a um estado “ estável”. É claro que isso exigiria que o OpenTok e a Video API da Vonage coexistissem temporariamente.

Observe que, durante esse processo gradual, seu aplicativo como um todo não estará mais totalmente funcional, pois o OpenTok e a Video API da Vonage são dois sistemas totalmente diferentes.

Você deve começar criando um “Adaptador de Vídeo” específico que agrupe todas as interações atuais com o OpenTok e, em seguida, substituir, uma a uma, as chamadas ao OpenTok pela Video API da Vonage.

Outra abordagem poderia ser duplicar esse “Adaptador de Vídeo” para criar um novo “Adaptador de Vídeo Vonage”, dedicado a essa migração, antes de trocar esses dois adaptadores entre si. Saiba mais com o Padrão da figueira-estranguladora

Recomendações para testes

Testes minuciosos são essenciais para uma transição tranquila, tanto durante quanto após a migração. Isso inclui não apenas testes unitários, mas também testes de integração e de regressão. Também vale a pena testar manualmente o fluxo do seu aplicativo pelo menos uma vez antes e depois da migração para garantir que seus testes automatizados funcionem como esperado ou para identificar quaisquer problemas que os testes possam não ter detectado. Você pode até considerar a criação de testes de equivalência. A ideia é criar um conjunto de testes que comprove que tanto a versão OpenTok quanto a versão Vonage Video do seu aplicativo funcionam da mesma maneira. Esses testes podem ser descartados assim que a transição estiver concluída e a versão OpenTok do seu aplicativo for removida.

Solução de problemas e suporte

Perguntas frequentes

Isso está explicado no README do SDK.

Isso está explicado no README do SDK.

Canais de suporte

Para obter ajuda geral e participar de discussões sobre a migração para o Vonage Video, confira o Canal #Video API no nosso Slack da Comunidade, onde você pode obter respostas da equipe da Vonage e de outros usuários. Você também pode entrar em contato conosco pelo X @VonageDev. O principal ponto de contato para quaisquer questões relacionadas à própria Video API é support@api.vonage.com. Se você encontrar um bug no SDK, por favor, abrir um ticket no GitHub com os passos para reproduzir o problema.