Vonage Video-Übergangsleitfaden für .NET

Der Übergang von `Opentok-.NET-SDK` zu `vonage-dotnet-sdk`

Einführung

Zweck

Das Ziel dieses Dokuments ist es, einen Ausgangspunkt für den Übergang vom OpenTok .NET Server SDK zum Vonage .NET Server SDK.

Umfang

Dieses Dokument geht davon aus, dass Sie mindestens die Version 3.14.0 oder später von der OpenTok .NET SDK.

Die Video API wurde dem .NET Server SDK in der Version 6.14.0. Sie sollten die neueste Version des Vonage .NET SDK verwenden, die Sie unter auf GitHub oder NuGet.

Annahmen

Dieser Leitfaden richtet sich an einen professionellen Softwareentwickler. Es werden zumindest grundlegende Kenntnisse über .NET, gängige .NET-Entwicklerwerkzeuge, Build-Systeme und Git (oder ein anderes Versionskontrollsystem) Versionskontrollsystem) wird vorausgesetzt. Sie sollten mit dem Lesen und Schreiben von .NET-Code, der Verwaltung von Projektabhängigkeiten, der Bereitstellung und Ausführung eines .NET Projekts. Eine Einführung in die .NET-Sprache, -Plattform und -Werkzeuge würde den Rahmen dieses Dokuments sprengen.

Ressourcen

Die folgenden Links sind nützlich für weiterführende Lektüre zu diesem Dokument und als Referenz für alles, was nicht in diesem Dokument behandelt wird in diesem Dokument nicht behandelt werden:

Vonage

TokBox

Planung Ihrer Migration

Bevor Sie von OpenTok auf Vonage Video umsteigen, sollten Sie den Umfang der Aufgabe bedenken, um realistische Erwartungen.

Bewertung der Auswirkungen

Die erste Frage, die es zu beantworten gilt, lautet: Wie viel des Codes Ihrer Anwendung hängt vom OpenTok SDK ab? Erstellen Sie eine Liste aller Dateien, in denen das SDK direkt verwendet wird. Das heißt, jede .cs Datei, die eine using OpenTokSDK Referenz. Sie können die Dateien in Ihrem Projekt nach der Anweisung durchsuchen using OpenTokSDK mit einer IDE (Strg+Umschalt+F) oder einem Befehlszeilentool, um die betroffenen Dateien zu identifizieren.

Zeitleiste

Berücksichtigen Sie die Zeit, die für die Umstellung erforderlich ist. Dies hängt von Ihrer Erfahrung mit dem Projekt und seinen Auswirkungen sowie von den Tests ab. Es ist von entscheidender Bedeutung, eine gute Test-Suite zu haben, damit Sie die Gleichwertigkeit zwischen OpenTok und Vonage Video überprüfen können. Die Zeit, die für die Umstellung benötigt wird, ist ungefähr proportional zu der Anzahl der Stellen, an denen das OpenTok SDK in Ihrem Code verwendet wird, sowie der Vielfalt der verwendeten Funktionen. Einige API-Aufrufe werden einfacher zu ersetzen sein als andere.

Versionierung

OpenTok und Vonage Video sind zwei unterschiedliche Produkte - dies macht eine schrittweise Migration unmöglich.

Für den Übergang sollten Sie einen temporären Zweig in Ihrem Versionskontrollsystem anlegen, damit Sie Änderungen schrittweise und häufig vornehmen können, ohne das bestehende Projekt zu zerstören. Sie können auch die Tests des bestehenden Projekts als Orakel für die Korrektheit verwenden. Idealerweise sollten Sie den Übergangszweig erst dann mit dem Hauptzweig zusammenführen, wenn Sie die Konvertierung abgeschlossen haben.

Wichtige Änderungen und Überlegungen

Neue Funktionen und Standards

Die Vonage Video API hat die gleichen Funktionen wie OpenTok, und das .NET SDK wird aktiv gepflegt, um mit der API Spezifikation zu entsprechen. Dennoch gibt es einige wesentliche Unterschiede zwischen dem OpenTok und Vonage .NET SDK.

Eine davon ist die Verwendung von geeigneten Datenmodellen anstelle von primitiven Typen. Der Zweck ist vermeiden "primitive Besessenheit", indem man den Methodensignaturen mehr Domänenkontext Methodensignaturen.

Ein weiteres Beispiel ist die umfassende Verwendung von Monaden, als herkömmliche Ausnahmen, um einen funktionelleren Ansatz für die Fehlerbehandlung zu bieten. Auch wenn Monads für Entwickler ein neues Konzept sind, bringen sie wertvolle Vorteile wie Transparenz und Vorhersagbarkeit und bleiben dabei ausnahmefrei. Zum Beispiel wird beim Erstellen einer neuen Sitzung ein Task<Result<CreateSessionResponse>> - a Result<T> stellt das das Ergebnis einer Operation, die fehlschlagen kann, und zeigt zwei mögliche Zustände an: einen Success oder eine Failure. In diesem besonderen Szenario ist die Result enthält eine CreateSessionResponse wenn der Vorgang erfolgreich war, oder eine IResultFailure wenn er gescheitert ist.

Paket-Update

Als erstes müssen Sie das Vonage .NET SDK in Ihrem Projekt installieren oder aktualisieren. Sie können dies mit dem in Ihrer IDE integrierten NuGet-Paketmanager tun (suchen Sie nach Vonage), oder indem Sie den folgenden Befehl in Ihrem Terminal ausführen: dotnet add package Vonage.

Für eine schrittweise Migration können Sie sowohl OpenTok- als auch Vonage-Abhängigkeiten in Ihr Projekt aufnehmen. Wir empfehlen jedoch dringend, dies nur zu Testzwecken zu tun und nicht in der Produktion einzusetzen, da das OpenTok SDK dazu neigt, ältere ältere Versionen von Abhängigkeiten zu verwenden, die zur Laufzeit Probleme verursachen können.

Änderungen bei der Authentifizierung

Die Authentifizierung wird sowohl bei OpenTok als auch bei Vonage .NET Server SDKs für Sie durchgeführt, so dass Sie Ihre Account einmal bei der Initialisierung angeben. Der Unterschied besteht darin, dass OpenTok einen API-Schlüssel und ein Geheimnis benötigt, während für die Video API im Vonage .NET SDK müssen Sie eine Anwendungs-ID und den dazugehörigen privaten Schlüssel angeben. Während sowohl Vonage als auch OpenTok Token-basierte Authentifizierung verwenden, sind die Token von Vonage JWTs während OpenTok ein eigenes Format verwendet. Während Sie einen API-Schlüssel und ein Geheimnis für die VonageClient Genau wie bei OpenTok wird dies für andere Vonage-APIs verwendet, nicht für Video. Daher müssen Sie eine bestehende Anwendung erstellen oder verwenden.

Sie können eine Anwendung aus dem Menü Vonage Dashboard. Stellen Sie sicher, dass Ihre Anwendung die Videofunktion aktiviert hat. Klicken Sie auf "Bearbeiten" für eine bestehende Applikation, um deren Fähigkeiten und Anmeldeinformationen anzuzeigen. Klicken Sie hier auf "Öffentlichen und privaten Schlüssel generieren". Dieser Vorgang sollte nur einmal durchgeführt werden, da sich jedes Mal, wenn Sie jedes Mal, wenn Sie dies tun, ändern sich die Anmeldeinformationen, wodurch das bestehende Schlüsselpaar zerstört wird. Wenn Sie auf diese Schaltfläche klicken, wird ein Download Ihres privaten Schlüssels. Sie sollten diese Datei zu Testzwecken an einem sicheren Ort ablegen. GEBEN SIE NIEMALS IHREN PRIVATEN SCHLÜSSEL WEITER ODER VERÖFFENTLICHEN SIE IHN! Der private Schlüssel ist quasi das "Passwort" für Ihre Anwendung und sollte daher sorgfältig behandelt werden. Es wird empfohlen, dass dass Sie Ihre Anwendungs-ID und Ihren privaten Schlüssel zu Ihrer Einstellungsdatei oder KeyVault hinzufügen. Siehe mehr hier wie Sie das SDK konfigurieren können.

Weitere Hinweise zum Einrichten einer Anwendung, siehe die Anleitung "Erste Schritte.

Verwendung

Siehe das .NET SDK README für Anweisungen zur Einrichtung.

Stattdessen wird mit OpenTok:

var client = new OpenTok(apiKey, apiSecret);

Gehen Sie wie folgt vor:

// 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;
}

Sobald Sie Zugang zu einem IVideoClient Instanz können Sie die Video API.

Ausführlichere Anweisungen zur Verwendung finden Sie im die .NET Sever SDK Videoanleitung.

Änderungen der Methode

Es gibt einige Änderungen bei den Methoden zwischen der OpenTok SDK und die Video API-Implementierung in der Vonage SDKs.

Jede Operation gibt eine Result<T>und gibt an, ob der Vorgang erfolgreich war oder fehlgeschlagen ist. Für weitere Einzelheiten, werfen Sie einen Blick auf die Monaden Abschnitt.
Wenn Sie eine Anfrage erstellen, sind Sie auf einen Builder angewiesen (z. B: CreateSessionRequest.Build()...) - alle Builder bieten eine flüssige API, die Sie durch die obligatorischen Parameter führt, während sie optionale Parameter vorschlägt, bevor sie die Anfrage erstellt verwenden .Create().
Die Methoden waren früher sowohl in synchronen als auch in asynchronen Versionen verfügbar. Die synchronen Versionen wurden entfernt, so dass nur noch die asynchrone Version übrig ist. Wenn Sie die Methode dennoch in einem synchronen Prozess ausführen möchten, sollten Sie zu verwenden. Task.Wait() oder Task.Result über die zurückgegebenen Task Objekt.
Einige Methoden wurden umbenannt und/oder verschoben, um sie übersichtlicher zu gestalten und/oder um ihre Funktion besser zu verdeutlichen. Diese sind unten aufgeführt:

OpenTok Methode Name	Vonage Video Methode Name
`OpenTok.GenerateToken`	`VideoTokenGenerator.GenerateToken`
`OpenTok.CreateSessionAsync`	`VonageClient.SessionClient.CreateSessionAsync`
`OpenTok.StartArchiveAsync`	`VonageClient.ArchiveClient.CreateArchiveAsync`
`OpenTok.StopArchiveAsync`	`VonageClient.ArchiveClient.StopArchiveAsync`
`OpenTok.GetArchiveAsync`	`VonageClient.ArchiveClient.GetArchiveAsync`
`OpenTok.DeleteArchiveAsync`	`VonageClient.ArchiveClient.DeleteArchiveAsync`
`OpenTok.ListArchivesAsync`	`VonageClient.ArchiveClient.GetArchivesAsync`
`OpenTok.AddStreamToArchiveAsync`	`VonageClient.ArchiveClient.AddStreamAsync`
`OpenTok.RemoveStreamToArchiveAsync`	`VonageClient.ArchiveClient.RemoveStreamAsync`
`OpenTok.GetStreamAsync`	`VonageClient.BroadcastClient.GetStreamAsync`
`OpenTok.ListStreamsAsync`	`VonageClient.BroadcastClient.GetStreamsAsync`
`OpenTok.ForceMuteStreamAsync`	`VonageClient.ModerationClient.MuteStreamAsync`
`OpenTok.ForceMuteAllAsync`	`VonageClient.ModerationClient.MuteStreamsAsync`
`OpenTok.ForceDisconnectAsync`	`VonageClient.ModerationClient.DisconnectConnectionAsync`
`OpenTok.StartBroadcastAsync`	`VonageClient.BroadcastClient.StartBroadcastAsync`
`OpenTok.StopBroadcastAsync`	`VonageClient.BroadcastClient.StopBroadcastAsync`
`OpenTok.GetBroadcastAsync`	`VonageClient.BroadcastClient.GetBroadcastAsync`
`OpenTok.SetBroadcastLayout`	`VonageClient.BroadcastClient.ChangeBroadcastLayoutAsync`
`OpenTok.SignalAsync`	`VonageClient.SignalingClient.SendSignalAsyncAsync`
`OpenTok.PlayDTMFAsync`	`VonageClient.SipClient.PlayToneIntoCallAsync`
`OpenTok.DialAsync`	`VonageClient.SipClient.InitiateCallAsynb`

Strategien für die Migration

Inkrementelle Migration

Wir empfehlen eine schrittweise Migration, bei der Sie von einem Anwendungsfall zum nächsten wechseln und jedes Mal, wenn Sie in einem a " stabilen" Zustand gelangt. Das würde natürlich voraussetzen, dass OpenTok und Vonage Video API vorübergehend nebeneinander existieren.

Bitte beachten Sie, dass während eines solchen inkrementellen Prozesses Ihre Applikation als Ganzes nicht mehr voll funktionsfähig sein wird, da OpenTok und Vonage Video API zwei völlig unterschiedliche Systeme sind.

Sie sollten damit beginnen, einen speziellen "Video Adapter" zu erstellen, der der alle aktuellen Interaktionen mit OpenTok zusammenfasst und dann nach und nach die Verwendung von OpenTok durch die Vonage Video API ersetzt.

Ein anderer Ansatz könnte darin bestehen, den "Videoadapter" in einen neuen "Vonage-Videoadapter" zu duplizieren, der speziell für diese Migration, bevor man diese beiden Adapter zusammen austauscht. Siehe mehr mit der Würgefeigen-Muster

Test-Empfehlungen

Gründliche Tests sind für einen reibungslosen Übergang sowohl während als auch nach der Migration unerlässlich. Dazu gehören nicht nur Unit Tests, sondern auch Integrations- und Regressionstests. Es lohnt sich auch, den Ablauf Ihrer Anwendung mindestens einmal manuell zu testen vor und nach der Migration manuell zu testen, um sicherzustellen, dass Ihre automatisierten Tests das tun, was Sie glauben, dass sie es tun, oder um Probleme aufzuspüren Probleme aufzuspüren, die die Tests möglicherweise nicht erkannt haben. Sie können sogar die Erstellung von Äquivalenztests in Betracht ziehen. Die Idee ist, eine Suite zu erstellen, die sicherstellt, dass die OpenTok- und die Vonage Video-Version Ihrer Anwendung das Gleiche tun. Diese können Diese Tests können dann verworfen werden, sobald die Umstellung abgeschlossen ist und die OpenTok-Version Ihrer Anwendung entfernt wird.

Fehlersuche & Unterstützung

FAQs

Wie extrahiere ich einen Wert aus einer Result<T>?

Die Erklärung dazu finden Sie auf der README des SDK.

Was ist, wenn ich trotzdem Ausnahmen verwenden möchte?