Cliente Swift de ASP.NET Core SignalR

2025-04-18

SignalR Swift es una biblioteca cliente para conectarse a SignalR servidores desde aplicaciones Swift. En este documento se proporciona información general sobre cómo instalar el cliente, establecer una conexión, controlar llamadas de servidor a cliente, invocar métodos de servidor, trabajar con respuestas de streaming y configurar la reconexión automática y otras opciones.

Instalación del paquete de SignalR cliente

La SignalR biblioteca cliente de Swift se entrega como un paquete swift. Puede agregarlo al proyecto mediante el Administrador de paquetes Swift.

Requisitos

Swift >= 5.10
macOS >= 11.0
iOS >= 14

Instalación con el Administrador de paquetes Swift

Agregue el SignalR paquete swift como dependencia en el Package.swift archivo:

// 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")])
    ]
)

Después de agregar la dependencia, importe la biblioteca en el código swift:

import SignalRClient

Conexión a un centro

Para establecer una conexión, cree un HubConnectionBuilder y configúrelo con la dirección URL del servidor SignalR mediante el método withUrl(). Una vez creada la conexión, llame start() a para conectarse al servidor:

import SignalRClient

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

try await connection.start()

Llamada a métodos de cliente desde el centro

Para recibir mensajes del servidor, registre un controlador mediante el on método . El método on toma el nombre del método hub y un cierre que se ejecutará cuando el servidor llame a ese método.

En el siguiente nombre de método es ReceiveMessage. Los nombres de argumento son user y message:

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

El código anterior de connection.on se ejecuta cuando el código del lado servidor lo llama mediante el SendAsync método :

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 determina a qué método cliente se debe llamar mediante la coincidencia con el nombre del método y los argumentos definidos en SendAsync y connection.on.

Un procedimiento recomendado es llamar al método de try await connection.start() en el HubConnection después de on. Al hacerlo, se garantiza que los controladores se registran antes de recibir los mensajes.

Llamada a los métodos del centro desde el cliente

Los clientes de Swift pueden invocar métodos de concentrador en el servidor mediante los métodos invoke o send de HubConnection. El invoke método espera la respuesta del servidor y produce un error si se produce un error en la llamada, mientras que el send método no espera una respuesta.

En el código siguiente, el nombre del método en el centro es SendMessage. Los argumentos segundo y tercero que se pasan a invoke se asignan a los argumentos user y message del método del centro:

// 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")

El método invoke vuelve con el valor de devolución (si existe) cuando el método del servidor vuelve. Si el método del servidor produce un error, la función produce un error.

Registro

La biblioteca cliente de Swift incluye un sistema de registro ligero diseñado para aplicaciones Swift. Proporciona una manera estructurada de registrar mensajes en distintos niveles de gravedad mediante un controlador de registro personalizable. En las plataformas de Apple, utiliza os.Logger para un registro eficaz del sistema, mientras que en otras plataformas, vuelve a la salida de la consola estándar.

Nivel de registro

Use HubConnectionBuilder().withLogLevel(LogLevel:) para establecer el nivel de registro. Los mensajes se registran con el nivel de registro especificado y versiones posteriores:

LogLevel.debug: información detallada útil para la depuración.
LogLevel.information: mensajes generales de la aplicación.
LogLevel.warning: advertencias sobre posibles problemas.
LogLevel.error: errores que necesitan atención inmediata.

Resultados del cliente

Además de invocar métodos de servidor, el servidor puede llamar a métodos en el cliente y esperar una respuesta. Para ello, defina un controlador de cliente que devuelva un resultado de su cierre:

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

Por ejemplo, el servidor puede invocar el ClientResult método en el cliente y esperar el valor devuelto:

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

Trabajo con respuestas de streaming

Para recibir un flujo de datos del servidor, use el stream método . El método devuelve una secuencia que se puede iterar de forma asincrónica:

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

Control de la conexión perdida

Reconexión automática

El SignalR cliente swift admite la reconexión automática. Para habilitarlo, llame a withAutomaticReconnect() al establecer la conexión. La reconexión automática está deshabilitada de forma predeterminada.

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

Sin parámetros, withAutomaticReconnect() configura el cliente para esperar 0, 2, 10 y 30 segundos respectivamente antes de cada intento de reconexión. Después de cuatro intentos fallidos, el cliente deja de intentar volver a conectarse.

Antes de iniciar los intentos de reconexión, la HubConnection transiciona al estado Reconnecting y activa sus devoluciones de llamada onReconnecting.

Una vez que la reconexión se realiza correctamente, la HubConnection transiciona al estado connected y activa sus devoluciones de llamada onReconnected.

Una manera general de usar onReconnecting y onReconnected es marcar los cambios de estado de conexión:

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

connection.onReconnected {
    // connection is connected back
}

Configura la estrategia en la reconexión automática

Para personalizar el comportamiento de reconexión, puede pasar una matriz de números que represente el retraso en segundos antes de cada intento de reconexión. Para un control más granular, pase un objeto que se ajuste al protocolo RetryPolicy.

Uso de una matriz de valores de retraso

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()

Uso de una directiva de reintento personalizada

Implemente el protocolo RetryPolicy para controlar el tiempo de reconexión:

// 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()

Configurar las opciones de tiempo de espera y conexión persistente

Puede personalizar el tiempo de espera del cliente y la configuración de mantenimiento activo a través de HubConnectionBuilder:

Opciones	Valor predeterminado	Descripción
withKeepAliveInterval	15 (segundos)	Determina el intervalo en el que el cliente envía mensajes de ping y se establece directamente en HubConnectionBuilder. Esta configuración permite al servidor detectar desconexiones físicas, como cuando un cliente desconecta su equipo de la red. El envío de cualquier mensaje desde el cliente restablece el temporizador al inicio del intervalo. Si el cliente no ha enviado un mensaje en clientTimeoutInterval establecido en el servidor, el servidor considera que el cliente está desconectado.
withServerTimeout	30 (segundos)	Determina el intervalo en el que el cliente espera una respuesta del servidor antes de considerar el servidor desconectado. Esta configuración se establece directamente en HubConnectionBuilder.

Configuración del transporte

El SignalR cliente swift admite tres transportes: LongPolling, ServerSentEvents y WebSockets. De forma predeterminada, el cliente usará WebSockets si el servidor lo admite y volverá a ServerSentEvents y LongPolling si no lo admite. Puede configurar el cliente para que use un transporte específico mediante una llamada a withUrl(url:transport:) al compilar la conexión.

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()