ASP.NET Core SignalR Swift-Client

2025-04-18

SignalR Swift ist eine Clientbibliothek zum Herstellen einer Verbindung mit SignalR Servern aus Swift-Anwendungen. Dieses Dokument bietet eine Übersicht über die Installation des Clients, das Einrichten einer Verbindung, das Behandeln von Server-zu-Client-Aufrufen, das Aufrufen von Servermethoden, das Arbeiten mit Streamingantworten und das Konfigurieren der automatischen Erneutverbindung und anderer Optionen.

Installieren des SignalR Clientpakets

Die SignalR Swift-Clientbibliothek wird als Swift-Paket bereitgestellt. Sie können es ihrem Projekt mithilfe des Swift-Paket-Managers hinzufügen.

Anforderungen

Swift >= 5,10
macOS >= 11.0
iOS >= 14

Installieren mit Swift Package Manager

Fügen Sie das SignalR Swift-Paket als Abhängigkeit in Ihrer Package.swift Datei hinzu:

// swift-tools-version: 5.10
import PackageDescription

let package = Package(
    name: "signalr-client-app",
    dependencies: [
        .package(url: "https://github.com/dotnet/signalr-client-swift", branch: "main")
    ],
    targets: [
        .executableTarget(name: "YourTargetName", dependencies: [.product(name: "SignalRClient", package: "signalr-client-swift")])
    ]
)

Importieren Sie nach dem Hinzufügen der Abhängigkeit die Bibliothek in Ihrem Swift-Code:

import SignalRClient

Herstellen einer Verbindung mit einem Hub

Um eine Verbindung herzustellen, erstellen Sie eine HubConnectionBuilder und konfigurieren sie mit der URL Ihres SignalR Servers mithilfe der withUrl() Methode. Nachdem die Verbindung erstellt wurde, rufen Sie auf start() , um eine Verbindung mit dem Server herzustellen:

import SignalRClient

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server")
    .build()

try await connection.start()

Vom Hub aus Clientmethoden aufrufen

Um Nachrichten vom Server zu empfangen, registrieren Sie einen Handler mithilfe der on Methode. Die on Methode verwendet den Namen der Hubmethode und eine Schließung, die ausgeführt wird, wenn der Server diese Methode aufruft.

Im Folgenden lautet ReceiveMessageder Methodenname . Die Argumentnamen sind user und message:

await connection.on("ReceiveMessage") { (user: String, message: String) in
    print("\(user) says: \(message)")
}

Der vorstehende Code in connection.on wird ausgeführt, wenn serverseitiger Code ihn mithilfe der SendAsync Methode aufruft.

using Microsoft.AspNetCore.SignalR;
namespace SignalRChat.Hubs;

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
    {
        await Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

SignalR, bestimmt, welche Client-Methoden aufgerufen werden sollen, indem sie den Methodennamen und die Argumente abgleicht, die in SendAsync und connection.on definiert sind.

A Bestleistung ist der Anruf der Methode try await connection.start() am HubConnection nach on. Dadurch wird sichergestellt, dass die Handler registriert werden, bevor Nachrichten empfangen werden.

Aufrufen von Hubmethoden über den Client

Swift Clients können Hub-Methoden auf dem Server aufrufen, indem sie entweder die Methoden invoke oder send der HubConnection verwenden. Die invoke Methode wartet auf die Antwort des Servers und löst einen Fehler aus, wenn der Aufruf fehlschlägt, während die send Methode nicht auf eine Antwort wartet.

Im folgenden Code lautet SendMessageder Methodenname auf dem Hub . Die an invoke übergebenen zweiten und dritten Argumente entsprechen den Argumenten user und message der Hubmethode:

// Using invoke, which waits for a response
try await connection.invoke(method: "SendMessage", arguments: "myUser", "Hello")

// Using send, which does not wait for a response
try await connection.send(method: "SendMessage", arguments: "myUser", "Hello")

Die Methode invoke kehrt mit dem Rückgabewert (falls vorhanden) zurück, wenn die Methode auf dem Server zurückkehrt. Wenn die Methode auf dem Server einen Fehler auslöst, löst die Funktion einen Fehler aus.

Protokollierung

Die Swift-Clientbibliothek enthält ein einfaches Protokollierungssystem, das für Swift-Anwendungen entwickelt wurde. Sie bietet eine strukturierte Möglichkeit zum Protokollieren von Nachrichten auf unterschiedlichen Schweregraden mithilfe eines anpassbaren Protokollhandlers. Auf Apple-Plattformen nutzt es os.Logger für eine effiziente Systemprotokollierung, während es auf anderen Plattformen die Standardkonsolenausgabe verwendet.

Protokolliergrad

Verwenden Sie HubConnectionBuilder().withLogLevel(LogLevel:), um die Protokollebene festzulegen. Nachrichten werden mit der angegebenen Protokollebene und höher protokolliert:

LogLevel.debug: Detaillierte Informationen, die für das Debuggen nützlich sind.
LogLevel.information: Allgemeine Anwendungsmeldungen.
LogLevel.warning: Warnungen zu potenziellen Problemen.
LogLevel.error: Fehler, die sofortige Aufmerksamkeit benötigen.

Clientergebnisse

Zusätzlich zum Aufrufen von Servermethoden kann der Server Methoden auf dem Client aufrufen und auf eine Antwort warten. Um dies zu unterstützen, definieren Sie einen Client Handler, der ein Ergebnis aus seiner Schließung zurückgibt:

await connection.on("ClientResult") { (message: String) in
    return "client response"
}

Beispielsweise kann der Server die ClientResult Methode auf dem Client aufrufen und auf den zurückgegebenen Wert warten:

public class ChatHub : Hub
{
    public async Task TriggerClientResult()
    {
        var message = await Clients.Client(connectionId).InvokeAsync<string>("ClientResult");
    }
}

Arbeiten mit Streamingantworten

Verwenden Sie die stream Methode, um einen Datenstrom vom Server zu empfangen. Die Methode gibt einen Datenstrom zurück, den Sie asynchron durchlaufen können:

let streamResult: any StreamResult<String> = try await connection.stream(method: "StreamMethod")
for try await item in streamResult.stream {
    print("Received item: \(item)")
}

Verlorene Verbindung beheben

Automatische erneute Verbindung

Der SignalR Swift-Client unterstützt die automatische erneute Verbindung. Um sie zu aktivieren, rufen Sie withAutomaticReconnect() auf, während Sie die Verbindung aufbauen. Die automatische erneute Verbindung ist standardmäßig deaktiviert.

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server")
    .withAutomaticReconnect()
    .build()

Ohne Parameter konfiguriert withAutomaticReconnect() den Client so, dass er vor jedem erneuten Verbindungsversuch 0, 2, 10 und 30 Sekunden wartet. Nach vier fehlgeschlagenen Versuchen versucht der Client nicht mehr, die Verbindung wiederherzustellen.

Bevor Sie einen erneuten Verbindungsversuch starten, geht HubConnection in den Zustand Reconnecting über und feuert seine onReconnecting Rückrufe ab.

Nachdem die erneute Verbindung erfolgreich erfolgt ist, wechselt HubConnection in den connected Zustand und löst ihre onReconnected-Callbacks aus.

Eine allgemeine Möglichkeit, onReconnecting und onReconnected zu verwenden, ist die Markierung der Verbindungsstatusänderungen.

connection.onReconnecting { error in
    // connection is disconnected because of error
}

connection.onReconnected {
    // connection is connected back
}

Strategie für die automatische Wiederverbindung konfigurieren

Um das Verhalten der erneuten Verbindung anzupassen, können Sie ein Array von Zahlen übergeben, das die Verzögerung in Sekunden vor jedem erneuten Verbindungsversuch darstellt. Übergeben Sie für eine präzisere Kontrolle ein Objekt, das dem RetryPolicy-Protokoll entspricht.

Verwenden eines Arrays von Verzögerungswerten

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server")
    .withAutomaticReconnect([0, 0, 1]) // Wait 0, 0, and 1 second before each reconnect attempt; stop after 3 attempts.
    .build()

Verwendung einer benutzerdefinierten Wiederholungsrichtlinie

Setzen Sie das RetryPolicy-Protokoll um, um den Zeitpunkt der Verbindungswiederherstellung zu steuern.

// Define a custom retry policy
struct CustomRetryPolicy: RetryPolicy {
    func nextRetryInterval(retryContext: RetryContext) -> TimeInterval? {
        // For example, retry every 1 second indefinitely.
        return 1
    }
}

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server")
    .withAutomaticReconnect(CustomRetryPolicy())
    .build()

Konfigurieren von Timeout- und Keep-Alive-Optionen

Sie können die Timeout- und Keep-Alive-Einstellungen des Clients über den HubConnectionBuilder anpassen:

Optionen	Standardwert	BESCHREIBUNG
withKeepAliveInterval	15 (Sekunden)	Bestimmt das Intervall, in dem der Client Pingnachrichten sendet und direkt auf HubConnectionBuilder festgelegt wird. Diese Einstellung ermöglicht dem Server, das Erkennen harter Verbindungsabbrüche, z. B. wenn ein Client seinen Computer vom Netzwerk trennt. Durch das Senden einer Nachricht vom Client wird der Timer auf den Anfang des Intervalls zurückgesetzt. Wenn der Client innerhalb des auf dem Server festgelegten ClientTimeoutInterval keine Nachricht gesendet hat, betrachtet der Server den Client als getrennt.
withServerTimeout	30 (Sekunden)	Bestimmt das Intervall, in dem der Client auf eine Antwort vom Server wartet, bevor er den Server als nicht verbunden betrachtet. Diese Einstellung wird direkt auf HubConnectionBuilder festgelegt.

Konfigurieren des Transports

Der SignalR Swift-Client unterstützt drei Transporte: LongPolling, ServerSentEvents und WebSockets. Standardmäßig greift der Client auf WebSockets zurück, wenn der Server dies unterstützt, und auf ServerSentEvents und LongPolling, wenn dies nicht der Fall ist. Sie können den Client so konfigurieren, dass er einen bestimmten Transport verwendet, indem Sie beim Erstellen der Verbindung aufrufen withUrl(url:transport:) .

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server", transport: .webSockets) // use websocket only
    .build()

let connection = HubConnectionBuilder()
    .withUrl(url: "https://your-signalr-server", transport: [.webSockets, .serverSentEvents]) // use websockets and server sent events
    .build()

Freigeben über