ASP.NET Core SignalR Swift-klient

SignalR Swift är ett klientbibliotek för anslutning till SignalR servrar från Swift-program. Det här dokumentet innehåller en översikt över hur du installerar klienten, upprättar en anslutning, hanterar server-till-klient-anrop, anropar servermetoder, arbetar med strömningssvar och konfigurerar automatisk återanslutning och andra alternativ.

Installera SignalR-klientpaketet

SignalR Swift-klientbiblioteket levereras som ett Swift-paket. Du kan lägga till den i projektet med hjälp av Swift Package Manager-.

Krav

• Swift >= 5,10
• macOS >= 11,0
• iOS >= 14

Installera med Swift Package Manager

Lägg till SignalR Swift-paketet som ett beroende i din Package.swift-fil:

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

När du har lagt till beroendet importerar du biblioteket i Din Swift-kod:

import SignalRClient

Ansluta till en hubb

Om du vill upprätta en anslutning skapar du en HubConnectionBuilder och konfigurerar den med URL:en för din SignalR-server med hjälp av metoden withUrl(). När anslutningen har skapats anropar du start() för att ansluta till servern:

import SignalRClient

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

try await connection.start()

Anropa klientmetoder från hubben

Om du vill ta emot meddelanden från servern registrerar du en hanterare med hjälp av metoden on. Metoden on tar namnet på hubbmetoden och en closure som körs när servern anropar metoden.

I följande är metodnamnet ReceiveMessage. Argumentnamnen är user och message:

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

Föregående kod i connection.on körs när kod på serversidan anropar den med hjälp av metoden SendAsync:

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 avgör vilken klientmetod som ska anropas genom att matcha metodnamnet och argumenten som definierats i SendAsync och connection.on.

En god praxis är att anropa try await connection.start()-metoden på HubConnection efter on. Detta säkerställer att hanterarna registreras innan några meddelanden tas emot.

Anropa hubbmetoder från klienten

Swift-klienter kan anropa hubbmetoder på servern med hjälp av antingen invoke eller send metoder för HubConnection. Metoden invoke väntar på serverns svar och utlöser ett fel om anropet misslyckas, medan metoden send inte väntar på ett svar.

I följande kod är metodnamnet på hubben SendMessage. De andra och tredje argumenten som skickas till invoke mappar till hubbmetodens argument user och message.

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

Metoden invoke returnerar med returvärde (om något) när metoden på servern returnerar. Om metoden på servern utlöser ett fel utlöser funktionen ett fel.

Loggning / Skogsavverkning

Swift-klientbiblioteket innehåller ett enkelt loggningssystem som är utformat för Swift-program. Det ger ett strukturerat sätt att logga meddelanden på olika allvarlighetsnivåer med hjälp av en anpassningsbar logghanterare. På Apple-plattformar utnyttjar den os.Logger för effektiv systemloggning, medan den på andra plattformar återgår till standardkonsolens utdata.

Loggnivå

Använd HubConnectionBuilder().withLogLevel(LogLevel:) för att ange loggnivån. Meddelanden loggas med den angivna loggnivån och högre:

• LogLevel.debug: Detaljerad information som är användbar för felsökning.
• LogLevel.information: Allmänna programmeddelanden.
• LogLevel.warning: Varningar om potentiella problem.
• LogLevel.error: Fel som behöver åtgärdas omedelbart.

Klientresultat

Förutom att anropa servermetoder kan servern anropa metoder på klienten och invänta ett svar. För att stödja detta definierar du en klienthanterare som returnerar ett resultat från stängningen:

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

Servern kan till exempel anropa metoden ClientResult på klienten och vänta på det returnerade värdet:

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

Arbeta med strömmande svar

Om du vill ta emot en dataström från servern använder du metoden stream. Metoden returnerar en ström som du kan iterera över asynkront:

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

Hantera förlorad anslutning

Automatisk återanslutning

SignalR Swift-klienten stöder automatisk återanslutning. Om du vill aktivera det anropar du withAutomaticReconnect() när du skapar anslutningen. Automatisk återanslutning är inaktiverat som standard.

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

Utan parametrar konfigurerar withAutomaticReconnect() klienten att vänta 0, 2, 10 respektive 30 sekunder innan varje återanslutningsförsök. Efter fyra misslyckade försök slutar klienten att försöka återansluta.

Innan du påbörjar några återanslutningsförsök övergår HubConnection till tillståndet Reconnecting och utlöser dess onReconnecting återanrop.

När återanslutningen har slutförts går HubConnection över till tillståndet connected och utlöser sina onReconnected återanrop.

Ett allmänt sätt att använda onReconnecting och onReconnected är att markera ändringar i anslutningstillståndet:

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

connection.onReconnected {
    // connection is connected back
}

Konfigurera strategi vid automatisk återanslutning

Om du vill anpassa återanslutningsbeteendet kan du skicka en matris med tal som representerar fördröjningen i sekunder före varje återanslutningsförsök. För mer detaljerad kontroll skickar du ett objekt som överensstämmer med RetryPolicy-protokollet.

Använda en matris med fördröjningsvärden

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

Använda en anpassad återförsöksprincip

Implementera RetryPolicy-protokollet för att styra återanslutningstidpunkten:

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

Konfigurera timeout- och keep-alive-alternativ

Du kan anpassa klientens timeout- och keep-alive-inställningar via HubConnectionBuilder:

Konfigurera transport

SignalR Swift-klienten stöder tre transporter: LongPolling, ServerSentEvents och WebSockets. Som standard använder klienten WebSockets om servern stöder det och återgår till ServerSentEvents och LongPolling om det inte gör det. Du kan konfigurera klienten att använda en specifik transport genom att anropa withUrl(url:transport:) när du skapar anslutningen.

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

Ytterligare resurser

• En handledning om WebPack och TypeScript
• Nav
• .NET-klient
• JavaScript-klient
• Publicera till Azure
• CORS-begäranden (Cross-Origin Requests)
• Dokumentation om serverlösa Azure-tjänster SignalR
• Felsöka anslutningsfel