ASP.NET Core SignalR nasıl çalışır?

  • 8 dakika

Sunucular ve Hub sınıfı

Hub sınıfı bir SignalR sunucu kavramıdır. Ad alanı Microsoft.AspNetCore.SignalR içinde tanımlanır ve Microsoft.AspNetCore.SignalR NuGet paketinin bir parçasıdır. ASP.NET Microsoft.NET.Sdk.Web SDK'sını hedefleyen Core web uygulamalarının, paylaşılan çerçevenin bir parçası olarak zaten kullanılabilir olduğundan SignalR için paket başvurusu eklemesi gerekmez.

bir Hub yol üzerinden kullanıma sunulur. Örneğin, https://www.contoso-pizza.com/hubs/orders bir OrdersHub uygulamayı temsil etmek için yol kullanılabilir. Çeşitli hub API'leri aracılığıyla, yazarlar yöntemleri ve olayları tanımlayabilir.

Hub'da yöntemleri kullanıma sunmanın iki yöntemi vardır. Aşağıdaki türlerin ve yazma yöntemlerinin bir alt sınıfını oluşturursunuz:

  • Hub: Standart bir hub.
  • Hub<T>: Kesin olarak yazılan genel hub.

Örnek Hub

Başvuru noktası olarak aşağıdaki Notification nesneyi göz önünde bulundurun:

namespace RealTime.Models;

public record Notification(string Text, DateTime Date);

.NET istemci SDK'sını kullandığınızda nesne paylaşılabilir, böylece sunucu ve istemci tam olarak aynı nesneye sahip olur. Bir bildirim hub'ı düşünün:

using Microsoft.AspNetCore.SignalR;
using System;
using System.Threading.Tasks;
using RealTime.Models;

namespace ExampleServer.Hubs;

public sealed class NotificationHub : Hub
{
    public Task NotifyAll(Notification notification) =>
        Clients.All.SendAsync("NotificationReceived", notification);
}

Yöntemler ve olaylar arasındaki farkla ilgili olarak, önceki hub uygulamasındaki yöntem olur NotifyAllve olay olur NotificationReceived. NotificationHub , öğesinin bir alt sınıfıdır Hub. NotifyAll yöntemi bir Taskdöndürür ve tek Notification bir parametre kabul eder. yöntemi, tüm bağlı istemcileri temsil eden ' den Clients.Allçağrısı SendAsync olarak ifade edilir. Olaya NotificationReceived bağlı notification olarak tetiklenir.

Örnek IHubContext

Olayları bir veya bir IHubContext örnekten tetiklersiniz. Hub SignalR hub'ı, SignalR sunucusuna bağlı istemcilere ileti göndermeye yönelik temel soyutlamadır. Aşağıdaki türlerden birini kullanarak uygulamanızdaki diğer yerlerden ileti göndermek de mümkündür:

  • IHubContext<THub>: Standart hub'ı temsil eden THub bağlam.
  • IHubContext<THub,T>: Kesin olarak belirlenmiş bir genel hub'ı ve T karşılık gelen istemci türünü temsil eden bağlamTHub.

Önemli

IHubContext , istemcilere bildirim göndermeye yöneliktir. üzerindeki yöntemleri Hubçağırmak için kullanılmaz.

Bir örnek IHubContext

Önceki bildirim hub'ı uygulamasını göz önünde bulundurarak aşağıdaki gibi kullanabilirsiniz IHubContext<NotificationHub> :

using Microsoft.AspNetCore.SignalR;
using System;
using System.Threading.Tasks;
using RealTime.Models;

namespace ExampleServer.Services;

public sealed class NotificationService(
    IHubContext<NotificationHub> hubContext)
{
    public Task SendNotificationAsync(Notification notification) =>
        notification is not null
            ? hubContext.Clients.All.SendAsync("NotificationReceived", notification)
            : Task.CompletedTask;
}

Yukarıdaki C# kodu, istemcilerin bağlamsal listesine erişmeye dayanır IHubContext<NotificationHub> ve bildirimleri yayınlama özelliğini gösterir. Kapsamda hubContext yakalanan birincil oluşturucu parametresi olayı tetiklerken "NotificationReceived" kullanılır, ancak hub'ın NotifyAll yöntemini çağırmak için kullanılması amaçlanmamıştır.

Yöntemler

Hub veya Hub<T> yöntemleri diğer C# yöntemleri gibidir. Bir dönüş türü, yöntem adı ve parametreler tanımlar.

  • Hub yöntemi için en yaygın dönüş türü, zaman uyumsuz hub işlemini temsil eden veya Task<TResult>'dirTask.
  • Yöntem adı, istemcilerden yöntemini çağırmak için kullanılır. kullanarak HubMethodNameAttributeözelleştirebilirsiniz.
  • Parametreler isteğe bağlıdır, ancak tanımlandığında istemcilerin karşılık gelen bağımsız değişkenleri sağlaması beklenir.

Olayları tetiklemek için yöntemler gerekmez, ancak genellikle böyle olur.

Ekinlikler

Bir olaya istemciden ada göre abone olunabilir. Sunucu olayları oluşturmakla sorumludur. Hub, Hub<T>, IHubContext<THub>ve IHubContext<THub, T> olayları adlandırılır ve en fazla 10 parametre tanımlayabilir. Olaylar sunucuda tetiklenir ve ilgili istemciler tarafından işlenir. İstemci, hub'ına bağlı olaylara abone olduğunda ilgilenmiş olarak kabul edilir. İstemciler, çağrıları sonucunda olayları tetikleyen hub yöntemlerini çağırdığında dolaylı olarak olayları tetikleyebilir. Ancak, sunucunun sorumluluğu bu olduğundan olaylar istemciler tarafından doğrudan tetiklenemez.

Olay istemci kapsamları

Bir IClientProxy örnekten olayları çağırırsınız. ve IHubCallerClients arabirimlerini türünden Clients uygularsınızIHubClients. Belirli IClientProxy bir örneği kapsamanın birçok yolu vardır. özelliğinden Hub.Clients aşağıdaki kapsamları hedefleyebilirsiniz:

Üye Ayrıntılar
All Tüm bağlı istemciler (yayın gibi).
AllExcept Belirtilen bağlantılar (filtrelenmiş yayın gibi) hariç tüm bağlı istemciler.
Caller Yöntemini tetikleyen bağlı istemci (yankı gibi).
Client Belirtilen istemci bağlantısı (tek bağlantı).
Clients Belirtilen istemci bağlantıları (birden çok bağlantı).
Group Belirtilen grup içindeki tüm bağlı istemciler.
GroupExcept Belirtilen bağlantılar hariç, belirtilen grup içindeki tüm bağlı istemciler.
Groups Belirtilen gruplar içindeki tüm bağlı istemciler (birden çok grup).
Others Yöntemi tetikleyen istemci hariç tüm bağlı istemciler.
OthersInGroup Belirtilen grup içindeki tüm bağlı istemciler, yöntemi tetikleyen istemci hariç.
User Belirtilen kullanıcı için tüm bağlı istemciler (tek bir kullanıcı birden fazla cihazda bağlanabilir).
Users Belirtilen kullanıcılar için tüm bağlı istemciler.

Örnek kapsamlar

Hub'ın hedeflenen istemcilere nasıl ileti gönderdiğini görselleştirmenize yardımcı olabilecek aşağıdaki görüntüleri göz önünde bulundurun. Gelişmiş okunabilirlik için görüntüleri genişletebilirsiniz.

  • Tümüne yayınla

    ASP.NET Core SignalR hub sending message with Clients.All syntax.

    Tüm bağlı istemciler, ait olabilecekleri veya almadıkları grup ne olursa olsun bu iletiyi alır.

  • Yalıtılmış kullanıcı

    ASP.NET Core SignalR hub sending message with Clients.User syntax.

    Şu anda kaç cihaz kullandığından bağımsız olarak tek bir kullanıcı bu iletiyi alır.

  • Yalıtılmış grup

    ASP.NET Core SignalR hub sending message with Clients.Group syntax.

    Yalnızca belirli bir gruba ait istemciler bu iletiyi alır.

İstemciler ve HubConnection sınıfı

HubConnection sınıfı, istemcinin sunucusuna Hubolan bağlantısını temsil eden bir SignalR istemci kavramıdır. Ad alanı Microsoft.AspNetCore.SignalR.Client içinde tanımlanır ve Microsoft.AspNetCore.SignalR.Client NuGet paketinin bir parçasıdır.

Oluşturucu desenini ve karşılık gelen HubConnectionBuilder türü kullanarak bir HubConnection oluşturursunuz. Hub'ın yolu (veya System.Uri) göz önünde bulundurulduğunda bir HubConnectionoluşturabilirsiniz. Oluşturucu ayrıca günlüğe kaydetme, istenen protokol, kimlik doğrulama belirteci iletme ve otomatik yeniden bağlantı gibi diğer yapılandırma seçeneklerini de belirtebilir.

HubConnection API, sunucu bağlantısını başlatmak ve durdurmak için kullandığınız başlatma ve durdurma işlevlerini kullanıma sunar. Ayrıca akış, çağrı merkezi yöntemleri ve olaylara abone olma özellikleri vardır.

Örnek HubConnection oluşturma

.NET SignalR istemci SDK'sından nesne HubConnection oluşturmak için şu HubConnectionBuilder türü kullanırsınız:

using Microsoft.AspNetCore.SignalR.Client;
using System;
using System.Threading.Tasks;
using RealTime.Models;

namespace ExampleClient;

public sealed class Consumer : IAsyncDisposable
{
    private readonly string HostDomain =
        Environment.GetEnvironmentVariable("HOST_DOMAIN");
    
    private HubConnection _hubConnection;

    public Consumer()
    {
        _hubConnection = new HubConnectionBuilder()
            .WithUrl(new Uri($"{HostDomain}/hub/notifications"))
            .WithAutomaticReconnect()
            .Build();
    }

    public Task StartNotificationConnectionAsync() =>
        _hubConnection.StartAsync();

    public async ValueTask DisposeAsync()
    {
        if (_hubConnection is not null)
        {
            await _hubConnection.DisposeAsync();
            _hubConnection = null;
        }
    }
}

Çağrı hub'ı yöntemleri

bir istemciye başarıyla başlatılan bir istemci HubConnection örneği verilirse, bu istemci veya SendAsync uzantılarını kullanarak InvokeAsync bir hub'da yöntemleri çağırabilir. Hub yöntemi bir Task<TResult>döndürürse sonucu InvokeAsync<TResult> türünde TResultolur. Hub yöntemi döndürürse Tasksonuç olmaz. SendAsync Hem hem de InvokeAsync hub yönteminin adını ve sıfırdan 10 parametreye kadar gerektirir.

  • InvokeAsync: Belirtilen yöntem adını ve isteğe bağlı bağımsız değişkenleri kullanarak sunucuda bir hub yöntemi çağırır.
  • SendAsync: Belirtilen yöntem adını ve isteğe bağlı bağımsız değişkenleri kullanarak sunucuda bir hub yöntemi çağırır. Bu yöntem , alıcıdan bir yanıt beklemez .

Örnek hub yöntemi çağırma

Önceki Consumer sınıfa bir yöntem eklendiğindeSendNotificationAsync, SendNotificationAsync öğesine temsilci atar _hubConnection ve örneğe bağlı olarak Notification sunucunun hub'ına yöntemini çağırırNotifyAll.

public Task SendNotificationAsync(string text) =>
    _hubConnection.InvokeAsync(
        "NotifyAll", new Notification(text, DateTime.UtcNow));

Olayları işleme

Olayları işlemek için bir işleyiciyi örneğe HubConnection kaydedersiniz. Hub yönteminin HubConnectionExtensions.On adını bildiğinizde ve sıfırdan sekize kadar parametreye sahip olduğunuzda aşırı yüklemelerden birini çağırın. İşleyici aşağıdaki Action çeşitlemelerden herhangi birini karşılayabilir:

Alternatif olarak, bir çeşitleme olan zaman uyumsuz işleyici API'lerini Func<TResult> TResult Task kullanabilirsiniz:

Bir olay işleyicisinin kaydedilmesinin sonucu, abonelik olarak hizmet veren bir IDisposable'dir. İşleyicinin aboneliğini kaldırmak için öğesini çağırın Dispose.

Örnek olay kaydı

Önceki Consumer sınıfı güncelleştirerek bir işleyici sağlayarak ve çağırarak Onbir olaya kaydolursunuz:

using Microsoft.AspNetCore.SignalR.Client;
using System;
using System.Threading.Tasks;
using RealTime.Models;

namespace ExampleClient;

public sealed class Consumer : IAsyncDisposable
{
    private readonly string HostDomain =
        Environment.GetEnvironmentVariable("HOST_DOMAIN");
    
    private HubConnection _hubConnection;

    public Consumer()
    {
        _hubConnection = new HubConnectionBuilder()
            .WithUrl(new Uri($"{HostDomain}/hub/notifications"))
            .WithAutomaticReconnect()
            .Build();

        _hubConnection.On<Notification>(
            "NotificationReceived", OnNotificationReceivedAsync);
    }

    private async Task OnNotificationReceivedAsync(Notification notification)
    {
        // Do something meaningful with the notification.
        await Task.CompletedTask;
    }

    // Omitted for brevity.
}

OnNotificationReceivedAsync yöntemi, sunucunun hub örneği olayı tetiklediğinde çağrılır"NotificationReceived".

Contoso Pizza canlı sipariş güncelleştirmeleri

Web uygulamasının sunucu kodunun bir Hub uygulaması olması ve istemcilerin bir yolunu kullanıma sunması gerekir. , Hub izleme için bir grup oluşturmak için order nesnesinin benzersiz tanımlayıcısını kullanabilir. Tüm sipariş durumu değişiklik güncelleştirmeleri bu grupta iletilebilir.

Contoso Pizza uygulamasının bir Blazor WebAssembly uygulaması olduğunu belirtmek için istemci kodunun da güncelleştirilmesi gerekir. JavaScript SDK'sını veya .NET istemci SDK'sını kullanabilirsiniz. İstemci tarafı yoklama işlevini bir HubConnectionoluşturan kodla değiştirir ve ardından sunucu bağlantısını başlatırsınız. Sipariş izleme sayfasına gittiği sırada kodun değişiklik güncelleştirmelerinin gönderildiği siparişin belirli grubuna katılması gerekir. Sipariş durumu değişiklikleri için olaya abone olur ve ardından uygun şekilde işlersiniz.