چت بلادرنگ در .NET MAUI با SignalR: راهنمای WebSocket، اتصال مجدد خودکار و JWT در ۲۰۲۶

به‌روزرسانی: ۱۶ سپتامبر ۲۰۲۶

SignalR در .NET MAUI یک کتابخانه ارتباط بلادرنگ روی WebSocket است که با کمک Microsoft.AspNetCore.SignalR.Client به شما اجازه می‌دهد پیام‌ها را دوطرفه بین سرور ASP.NET Core و اپ موبایل رد و بدل کنید، اتصال مجدد خودکار داشته باشید و توکن JWT را برای احراز هویت هاب ارسال کنید. در این راهنما یک کلاینت چت واقعی می‌سازیم که با HubConnectionBuilder، پروتکل MessagePack و مدیریت درست چرخه حیات اپ در iOS و اندروید کار می‌کند. من این الگو را در سه اپ تولیدی پیاده کرده‌ام و رایج‌ترین اشتباهاتش را در همین متن پوشش می‌دهم.

SignalR چیست و چه زمانی در .NET MAUI به آن نیاز داریم؟

SignalR یک کتابخانه متن‌باز از تیم ASP.NET است که ارتباط بلادرنگ سرور با کلاینت را ساده می‌کند. به‌جای اینکه اپ موبایل هر چند ثانیه یک درخواست REST بزند (که اسمش را می‌گذارند «پول‌ کردن» یا polling)، سرور خودش هر زمان که داده جدیدی داشت به کلاینت‌های متصل push می‌کند. در پس‌ صحنه، SignalR ابتدا سعی می‌کند WebSocket برقرار کند و اگر شبکه اجازه نداد، به Server-Sent Events و در نهایت Long Polling سقوط می‌کند.

در .NET MAUI معمولاً چهار سناریو ما را به سمت SignalR می‌کشاند: چت زنده و پیام‌رسان‌های داخل اپ، نمایش قیمت زنده در اپ‌های مالی و کریپتو، همگام‌سازی وضعیت سفارش در اپ‌های تحویل غذا/سوپرمارکت، و نوتیفیکیشن‌های درون‌اپ (نه push سیستمی) که همان لحظه که کاربر داخل اپ است باید دیده شوند. اگر داده هر چند دقیقه یک بار به‌روز می‌شود و تأخیر مهم نیست، احتمالاً یک REST API با HttpClient و Refit کافی است و نیازی به هزینه پیچیدگی SignalR ندارید. ولی هر جا حس «زنده بودن» بخشی از تجربه است، SignalR انتخاب طبیعی است چون از هر دو سمت سرور ASP.NET Core و کلاینت .NET یک تیم پشتیبانی می‌کند.

طبق مستندات رسمی SignalR در Microsoft Learn، این کتابخانه از .NET Standard 2.0 به بالا پشتیبانی می‌شود و در .NET 9 و .NET MAUI بدون هیچ workaround اضافه‌ای کار می‌کند.

تفاوت WebSocket و SignalR چیست؟

WebSocket یک پروتکل استاندارد لایه ترابری است که یک اتصال دوطرفه پایدار بین کلاینت و سرور برقرار می‌کند. SignalR یک لایه بالاتر روی WebSocket (و چند حامل جایگزین) است که چند نگرانی رایج را برای شما حل می‌کند: پروتکل پیام‌ها را استاندارد می‌کند، مفهوم Hub و متدهای قابل فراخوانی از دو سمت را می‌آورد، اتصال مجدد خودکار دارد، از احراز هویت یکپارچه پشتیبانی می‌کند و پروتکل‌های مختلف Serialization (JSON و MessagePack) را قابل انتخاب می‌سازد.

در عمل، اگر مستقیم با کلاس ClientWebSocket در .NET کار کنید، باید خودتان اسکیمای پیام، پینگ/پونگ، بازپیوند در شبکه ناپایدار و مدیریت وضعیت را از صفر بنویسید. صادقانه بگویم، به تجربه چند اپ تولیدی، این مسیر تقریباً همیشه به بازنویسی نسخه ضعیف‌تری از SignalR ختم می‌شود. مگر اینکه با یک سرور غیر .NET (مثل Node یا Go) کار کنید که SignalR ندارد؛ در آن صورت WebSocket خام یا کتابخانه‌های دیگر مثل ‌‌‎MQTTnet منطقی‌ترند.

نصب و تنظیم SignalR در پروژه .NET MAUI

ابتدا پکیج کلاینت SignalR را به پروژه MAUI اضافه کنید. من همیشه نسخه را دقیقاً پین می‌کنم چون نسخه‌های Preview گاهی API را می‌شکنند:

dotnet add package Microsoft.AspNetCore.SignalR.Client --version 9.0.9
dotnet add package Microsoft.AspNetCore.SignalR.Protocols.MessagePack --version 9.0.9

سپس در MauiProgram.cs یک سرویس Singleton برای HubConnection ثبت کنید. دلیل Singleton بودن این است که اتصال SignalR گران است و می‌خواهیم در طول عمر اپ فقط یک نمونه داشته باشیم، نه اینکه هر بار که یک View باز می‌شود، اتصال جدید بزنیم.

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder.UseMauiApp<App>();

    builder.Services.AddSingleton<IChatHubClient, ChatHubClient>();
    builder.Services.AddSingleton<ITokenStore, SecureTokenStore>();
    builder.Services.AddTransient<ChatViewModel>();
    builder.Services.AddTransient<ChatPage>();

    return builder.Build();
}

پیاده‌سازی HubConnection و ارسال/دریافت پیام

حالا سرویس اصلی چت را بنویسیم. این سرویس مسئول ساخت HubConnection، ثبت handler برای متدهایی که سرور روی کلاینت صدا می‌زند، شروع اتصال و ارسال پیام است.

using Microsoft.AspNetCore.SignalR.Client;
using CommunityToolkit.Mvvm.Messaging;

public interface IChatHubClient
{
    Task ConnectAsync(CancellationToken ct = default);
    Task DisconnectAsync();
    Task SendMessageAsync(string roomId, string text);
    HubConnectionState State { get; }
    event EventHandler<HubConnectionState> StateChanged;
}

public sealed class ChatHubClient : IChatHubClient, IAsyncDisposable
{
    private readonly ITokenStore _tokens;
    private readonly IMessenger _messenger;
    private HubConnection? _connection;

    public ChatHubClient(ITokenStore tokens, IMessenger messenger)
    {
        _tokens = tokens;
        _messenger = messenger;
    }

    public HubConnectionState State => _connection?.State ?? HubConnectionState.Disconnected;
    public event EventHandler<HubConnectionState>? StateChanged;

    public async Task ConnectAsync(CancellationToken ct = default)
    {
        if (_connection is not null) return;

        _connection = new HubConnectionBuilder()
            .WithUrl("https://api.example.com/hubs/chat", options =>
            {
                options.AccessTokenProvider = async () => await _tokens.GetAccessTokenAsync();
                options.SkipNegotiation = true;
                options.Transports = Microsoft.AspNetCore.Http.Connections
                    .HttpTransportType.WebSockets;
            })
            .AddMessagePackProtocol()
            .WithAutomaticReconnect(new[]
            {
                TimeSpan.Zero,
                TimeSpan.FromSeconds(2),
                TimeSpan.FromSeconds(5),
                TimeSpan.FromSeconds(10),
                TimeSpan.FromSeconds(30)
            })
            .Build();

        _connection.On<ChatMessage>("ReceiveMessage", msg =>
            _messenger.Send(new ChatMessageReceived(msg)));

        _connection.Reconnecting += _ => { Notify(); return Task.CompletedTask; };
        _connection.Reconnected  += _ => { Notify(); return Task.CompletedTask; };
        _connection.Closed       += _ => { Notify(); return Task.CompletedTask; };

        await _connection.StartAsync(ct);
        Notify();
    }

    public Task SendMessageAsync(string roomId, string text) =>
        _connection?.State == HubConnectionState.Connected
            ? _connection.InvokeAsync("SendMessage", roomId, text)
            : Task.CompletedTask;

    public async Task DisconnectAsync()
    {
        if (_connection is null) return;
        await _connection.StopAsync();
        await _connection.DisposeAsync();
        _connection = null;
        Notify();
    }

    private void Notify() => StateChanged?.Invoke(this, State);
    public ValueTask DisposeAsync() => _connection?.DisposeAsync() ?? ValueTask.CompletedTask;
}

سمت سرور، هاب باید متد SendMessage را داشته باشد و متد ReceiveMessage را روی گروه اتاق فراخوانی کند. من ترجیح می‌دهم شناسه اتاق را قبل از انتشار validate کنم چون در غیر این صورت هر کاربر می‌تواند در گروه هر اتاقی پیام بفرستد.

احراز هویت SignalR با JWT در .NET MAUI

مشکل رایج: چطور توکن JWT را در WebSocket بفرستیم؟ استاندارد WebSocket اجازه هدر Authorization سفارشی در دست‌‌دادن اولیه نمی‌دهد (مرورگرها اجازه نمی‌دهند و کلاینت‌های موبایل هم برای سازگاری همین رفتار را دارند). راه‌حل SignalR این است که یک AccessTokenProvider بگیرد و توکن را به‌صورت query string با نام access_token اضافه کند.

سمت سرور ASP.NET Core باید JWT bearer را جوری تنظیم کند که هنگام اتصال به مسیر هاب، توکن را از query string بخواند:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters { /* ... */ };
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = context =>
            {
                var accessToken = context.Request.Query["access_token"];
                var path = context.HttpContext.Request.Path;
                if (!string.IsNullOrEmpty(accessToken) &&
                    path.StartsWithSegments("/hubs/chat"))
                {
                    context.Token = accessToken;
                }
                return Task.CompletedTask;
            }
        };
    });

سمت کلاینت، AccessTokenProvider باید توکن به‌روز را برگرداند. اگر توکن منقضی است، اول رفرش کنید و بعد توکن جدید را برگردانید. جزئیات رفرش توکن را در راهنمای احراز هویت JWT در .NET MAUI با SecureStorage پوشش داده‌ام؛ همان الگو دقیقاً اینجا هم جواب می‌دهد.

اتصال مجدد خودکار و مدیریت وضعیت اتصال

در موبایل، شبکه غیرقابل اتکاست: کاربر از Wi-Fi به 4G سوییچ می‌کند، در آسانسور می‌رود، تونل رد می‌کند. متد WithAutomaticReconnect با یک آرایه از TimeSpan تعریف می‌کند که پس از قطعی، چند بار و با چه فاصله‌ای اتصال مجدد را امتحان کند. اگر آرایه تمام شد، اتصال به وضعیت Disconnected می‌رود و باید دستی StartAsync صدا بزنید.

الگویی که در تولید کار می‌کند این است: در ViewModel یک متد OnAppearing داشته باشید که وضعیت اتصال را بررسی می‌کند و اگر Disconnected بود، دوباره ConnectAsync صدا می‌زند. علاوه بر آن، به رویداد Connectivity.Current.ConnectivityChanged از Microsoft.Maui.Networking گوش کنید — وقتی کاربر از حالت آفلاین به آنلاین می‌رود، این رویداد آتش می‌گیرد و شما می‌توانید یک ConnectAsync فوری بزنید بدون اینکه منتظر آرایه backoff بمانید.

Connectivity.Current.ConnectivityChanged += async (_, e) =>
{
    if (e.NetworkAccess == NetworkAccess.Internet &&
        _hub.State == HubConnectionState.Disconnected)
    {
        await _hub.ConnectAsync();
    }
};

نکته مهم: پس از هر بار Reconnected، پیام‌هایی که در بازه قطعی به شما نرسیده‌اند از دست رفته‌اند. من همیشه یک endpoint REST به نام /messages?since=timestamp دارم که پس از رویداد Reconnected پیام‌های ازدست‌رفته را می‌کشد. الگوی معماری Offline-First اینجا بسیار کمک‌کننده است چون همان صف Outbox می‌تواند پیام‌های ارسال‌نشده کاربر را هم مدیریت کند.

SignalR در پس‌زمینه اپ موبایل: iOS و اندروید

این جایی است که بیشتر توسعه‌دهندگان زخم می‌خورند. سیستم‌عامل iOS اجازه نمی‌دهد یک اپ عادی WebSocket را در پس‌زمینه نگه دارد؛ حدود ۳۰ ثانیه پس از اینکه اپ به پس‌زمینه رفت، اتصال TCP بسته می‌شود. اندروید کمی شل‌تر است ولی سیستم Doze از اندروید ۶ به بعد سوکت‌های idle را می‌بندد و اپ‌هایی که در پس‌زمینه پینگ می‌فرستند سریع در لیست بهینه‌سازی باتری قرار می‌گیرند.

راه‌حل درست این نیست که سعی کنید SignalR را در پس‌زمینه نگه دارید. راه درست این است که:

1. در App.OnSleep اتصال SignalR را با DisconnectAsync ببندید تا سیستم شما را جریمه نکند.
2. برای پیام‌های ضروری در پس‌زمینه، از Push Notification با Firebase Cloud Messaging استفاده کنید. این کاری است که واتساپ، تلگرام و همه اپ‌های چت تولیدی می‌کنند.
3. در App.OnResume دوباره ConnectAsync بزنید و پیام‌های ازدست‌رفته را از REST بازیابی کنید.

protected override void OnSleep()
{
    _ = _hub.DisconnectAsync();
    base.OnSleep();
}

protected override void OnResume()
{
    _ = ReconnectAndSyncAsync();
    base.OnResume();
}

private async Task ReconnectAndSyncAsync()
{
    await _hub.ConnectAsync();
    var lastSeen = await _prefs.GetAsync<DateTime>("lastSeenAt");
    await _messagesApi.SyncSinceAsync(lastSeen);
}

برای اپ‌هایی که واقعاً باید در پس‌زمینه فعال بمانند (اپ ناوبری، پخش موسیقی)، مبحث پس‌زمینه پیچیده‌تر است و باید مبحث تسک‌های پس‌زمینه با BGTaskScheduler و WorkManager را مطالعه کنید. اما برای چت‌های معمولی، Push + قطع اتصال در Sleep الگوی صنعتی است.

فعال‌سازی MessagePack برای کاهش پهنای باند

پیش‌فرض SignalR از JSON استفاده می‌کند. برای اپ موبایل، JSON از دو جهت گران است: اندازه بزرگ‌تر که ترافیک ۴G را بالا می‌برد، و پارس شدن Reflection-heavy که در دستگاه‌های ضعیف کند است. پروتکل MessagePack برای SignalR یک قالب باینری متراکم است که در تست‌های داخلی ما اندازه پیام‌های چت را ۳۵ تا ۴۵ درصد کاهش داد.

سمت کلاینت فقط .AddMessagePackProtocol() در builder کافی است. سمت سرور هم به همان روش تنظیم می‌شود:

builder.Services.AddSignalR()
    .AddMessagePackProtocol(options =>
    {
        options.SerializerOptions = MessagePackSerializerOptions.Standard
            .WithSecurity(MessagePackSecurity.UntrustedData);
    });

یک نکته که کمتر گفته می‌شود: MessagePack به‌صورت پیش‌فرض از IL Emit استفاده می‌کند که در iOS به‌خاطر AOT بودن کار نمی‌کند. باید Resolver مبتنی بر Source Generator را استفاده کنید یا از DynamicObjectResolver استاندارد که در MAUI اندروید و iOS هر دو کار می‌کند اما کمی کندتر است. سورس‌ژنراتور MessagePack (پکیج MessagePack.SourceGenerator) در سناریوی .NET MAUI با NativeAOT بهترین کارایی را می‌دهد.

اشتباهات رایج و راه‌حل‌ها

۱. اتصال HubConnection را در ViewModel بسازید

اگر HubConnectionBuilder را داخل هر ViewModel صدا بزنید، هر بار یک اتصال جدید ایجاد می‌شود که هم گران است هم چند اتصال هم‌زمان به سرور می‌فرستد و کاربر را تکراری در لیست آنلاین‌ها نشان می‌دهد. راه‌حل: سرویس Singleton، درست همان الگویی که در بالا نوشتم.

۲. توکن منقضی و شکست خاموش اتصال مجدد

اگر AccessTokenProvider توکن قدیمی برگرداند، هنگام اتصال مجدد سرور 401 برمی‌گرداند و اتصال به‌طور خاموش بسته می‌شود. حتماً در provider منطق رفرش توکن را داشته باشید و در صورت شکست، کاربر را به صفحه لاگین هدایت کنید.

۳. عدم لغو subscribe‌ها هنگام خروج از صفحه

اگر در ViewModel به _hub.StateChanged subscribe کنید و در Dispose از اشتراک خارج نشوید، حتی پس از بستن صفحه، ViewModel در حافظه می‌ماند و پیام‌ها را پردازش می‌کند. من در تجربه سه اپ تولیدی دیده‌ام این نشتی حافظه ۲۰-۳۰ مگابایت پس از یک ساعت استفاده باشد.

۴. UI Update در Thread غیر UI

هندلرهای On<T> در thread شبکه اجرا می‌شوند. اگر مستقیم UI را آپدیت کنید، در اندروید Exception می‌گیرید. راه‌حل: پیام را از طریق IMessenger بفرستید و در ViewModel با MainThread.BeginInvokeOnMainThread UI را آپدیت کنید.

۵. عدم مدیریت پیام‌های تکراری

پس از reconnect، سرور ممکن است چند پیام از‌دست‌رفته را دوباره بفرستد که با REST sync قبلی همپوشانی دارد. هر پیام باید یک شناسه یکتا داشته باشد و کلاینت قبل از افزودن به لیست، تکراری بودن را چک کند. من از HashSet<Guid> برای پیام‌های ۲۴ ساعت اخیر استفاده می‌کنم.