Menggunakan Azure SignalR Management SDK

Azure SignalR Management SDK membantu Anda mengelola klien SignalR melalui Azure SignalR Service secara langsung seperti pesan siaran. Oleh karena itu, SDK ini dapat digunakan di lingkungan tanpa server , tetapi tidak terbatas pada SDK ini. Anda dapat menggunakan SDK ini untuk mengelola klien SignalR yang terhubung ke Azure SignalR Service Anda di lingkungan apa pun, seperti di aplikasi konsol, di fungsi Azure atau di server web.

Catatan

Untuk melihat panduan untuk SDK versi 1.9.x dan sebelumnya, buka Azure SignalR Service Management SDK (Warisan). Anda mungkin juga ingin membaca Panduan migrasi.

Penting

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi.

string koneksi menyertakan informasi otorisasi yang diperlukan aplikasi Anda untuk mengakses Azure SignalR Service. Kunci akses di dalam string koneksi mirip dengan kata sandi root untuk layanan Anda. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan string koneksi Anda menggunakan ID Microsoft Entra dan mengotorisasi akses dengan ID Microsoft Entra.

Hindari mendistribusikan kunci akses ke pengguna lain, melakukan hard-coding, atau menyimpannya di mana saja dalam teks biasa yang dapat diakses orang lain. Putar kunci Anda jika Anda yakin bahwa kunci tersebut mungkin telah disusupi.

Fitur

Fitur	Perubahan sementara	Persisten
Siaran	✔️	✔️
Siaran kecuali beberapa klien	✔️	✔️
Kirim ke klien	✔️	✔️
Kirim ke klien	✔️	✔️
Kirim ke pengguna	✔️	✔️
Kirim ke pengguna	✔️	✔️
Mengirim ke grup	✔️	✔️
Kirim ke grup	✔️	✔️
Kirim ke grup kecuali beberapa klien	✔️	✔️
Menambahkan pengguna ke grup	✔️	✔️
Menghapus pengguna dari grup	✔️	✔️
Memeriksa apakah pengguna dalam grup	✔️	✔️

Dukungan beberapa instans layanan SignalR	❌	✔️
Dukungan klien MessagePack	sejak v1.21.0	sejak v1.20.0
Coba lagi kesalahan sementara	sejak v1.22.0	❌

Fitur hanya dilengkapi dengan API baru

Fitur	Perubahan sementara	Persisten
Periksa apakah ada koneksi	✔️	Sejak v1.11
Memeriksa apakah ada grup	✔️	Sejak v1.11
Memeriksa apakah pengguna ada	✔️	Sejak v1.11
Tutup sambungan klien	✔️	Sejak v1.11

Detail selengkapnya tentang berbagai mode dapat ditemukan di sini.
Sampel lengkap tentang SDK manajemen dapat ditemukan di sini.

Penggunaan

Bagian ini memperlihatkan cara menggunakan SDK Manajemen.

Membuat Service Manager

Buat instans Anda dari ServiceManagerServiceManagerBuilder.

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan string koneksi Anda menggunakan ID Microsoft Entra dan mengotorisasi akses dengan ID Microsoft Entra.


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

Anda dapat menggunakan ServiceManager untuk memeriksa kesehatan titik akhir Azure SignalR dan membuat konteks hub layanan. Bagian berikut ini menyediakan detail tentang membuat konteks hub layanan.

Untuk memeriksa kesehatan titik akhir Azure SignalR, Anda dapat menggunakan ServiceManager.IsServiceHealthy metode . Jika Anda memiliki beberapa titik akhir Azure SignalR, hanya titik akhir pertama yang dicentang.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Membuat Konteks Service Hub

Buat instans Anda dari ServiceHubContextServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Catatan

Membuat ServiceHubContext adalah operasi yang agak mahal. Disarankan untuk menggunakan kembali instans yang sama ServiceHubContext untuk hub yang sama.

Negosiasi

Dalam mode default, titik /<Your Hub Name>/negotiate akhir diekspos untuk negosiasi oleh Azure SignalR Service SDK. Klien SignalR mencapai titik akhir ini lalu mengalihkan ke Azure SignalR Service nanti.

Dalam mode tanpa server, kami sarankan Anda menghosting titik akhir negosiasi untuk melayani permintaan negosiasi klien SignalR dan mengalihkan klien ke Azure SignalR Service.

Petunjuk / Saran

Baca detail selengkapnya tentang pengalihan di Protokol Negosiasi SignalR.

Baik titik akhir maupun token akses berguna saat Anda ingin mengalihkan klien SignalR ke Azure SignalR Service Anda.

Anda dapat menggunakan instans ServiceHubContext untuk menghasilkan url titik akhir dan token akses yang sesuai untuk klien SignalR untuk terhubung ke Azure SignalR Service Anda.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Misalkan titik akhir hub Anda adalah http://<Your Host Name>/<Your Hub Name>, maka titik akhir negosiasi Anda adalah http://<Your Host Name>/<Your Hub Name>/negotiate. Setelah Anda menghosting titik akhir negosiasi, Anda dapat menggunakan klien SignalR untuk terhubung ke hub Anda seperti ini:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

Sampel tentang cara menggunakan SDK Manajemen untuk mengalihkan klien SignalR ke Azure SignalR Service dapat ditemukan di sini.

Mengirim pesan dan mengelola grup

yang ServiceHubContext kita bangun dari ServiceHubContextBuilder adalah kelas yang mengimplementasikan dan memperluas IServiceHubContext. Anda dapat menggunakannya untuk mengirim pesan ke klien Anda dan mengelola grup Anda.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Hub yang sangat ditik

Hub yang sangat ditik adalah model pemrograman yang dapat Anda ekstrak metode klien Anda ke antarmuka, sehingga menghindari kesalahan seperti salah eja nama metode atau meneruskan jenis parameter yang salah.

Katakanlah kita memiliki metode klien yang disebut ReceivedMessage dengan dua parameter string. Tanpa hub yang sangat ditik, Anda menyiarkan ke klien melalui hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). Dengan hub yang sangat ditik, Anda terlebih dahulu menentukan antarmuka seperti ini:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

Dan kemudian Anda membuat konteks hub yang sangat ditik, yang mengimplementasikan IHubContext<Hub<T>, T>, T adalah antarmuka metode klien Anda:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Akhirnya, Anda dapat langsung memanggil metode :

await Clients.All.ReceiveMessage(user, message);

Kecuali untuk perbedaan pengiriman pesan, Anda dapat menegosiasikan atau mengelola grup dengan ServiceHubContext<T> seperti ServiceHubContext.

Baca selengkapnya tentang hub yang sangat ditik di dokumen ASP.NET Core di sini.

Jenis transportasi

SDK ini dapat berkomunikasi ke Azure SignalR Service dengan dua jenis transportasi:

Sementara: Buat permintaan HTTP Azure SignalR Service untuk setiap pesan yang dikirim. SDK hanya membungkus Azure SignalR Service REST API dalam mode Sementara. Ini berguna ketika Anda tidak dapat membuat koneksi WebSockets.
Persisten: Buat koneksi WebSockets terlebih dahulu lalu kirim semua pesan dalam koneksi ini. Ini berguna saat Anda mengirim pesan dalam jumlah besar.

Ringkasan perilaku serialisasi argumen dalam pesan

Serialisasi	Perubahan sementara	Persisten
Pustaka JSON default	`Newtonsoft.Json`	Sama seperti ASP.NET Core SignalR: `Newtonsoft.Json` untuk .NET Standard 2.0; `System.Text.Json` untuk .NET Core App 3.1 ke atas
Dukungan klien MessagePack	sejak v1.21.0	sejak v1.20.0

Serialisasi JSON

Di SDK Manajemen, argumen metode yang dikirim ke klien diserialisasikan ke JSON. Kami memiliki beberapa cara untuk menyesuaikan serialisasi JSON. Kami menunjukkan semua cara dalam urutan dari yang paling direkomendasikan hingga yang paling tidak direkomendasikan.

`ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)`

Cara yang paling direkomendasikan adalah menggunakan kelas ObjectSerializerabstrak umum , karena mendukung pustaka serialisasi JSON yang berbeda seperti System.Text.Json dan Newtonsoft.Json dan berlaku untuk semua jenis transportasi. Biasanya Anda tidak perlu mengimplementasikan ObjectSerializer diri Sendiri, karena implementasi JSON yang berguna untuk System.Text.Json dan Newtonsoft.Json sudah disediakan.

Saat menggunakan System.Text.Json sebagai pustaka pemrosesan JSON Yang digunakan bawaan JsonObjectSerializerSystem.Text.Json.JsonSerializer untuk serialisasi/deserialisasi. Berikut adalah sampel untuk menggunakan penamaan kasus camel untuk serialisasi JSON:

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();

Saat menggunakan Newtonsoft.Json sebagai pustaka pemrosesan JSON Pertama-tama instal paket Microsoft.Azure.Core.NewtonsoftJson dari NuGet menggunakan .NET CLI:

dotnet add package Microsoft.Azure.Core.NewtonsoftJson

Berikut adalah sampel untuk menggunakan penamaan kasus unta dengan NewtonsoftJsonObjectSerializer:

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

Saat menggunakan pustaka pemrosesan JSON lainnya

Anda juga dapat menerapkan ObjectSerializer sendiri. Tautan berikut mungkin membantu:
- Referensi API dari ObjectSerializer
- Referensi API dari JsonObjectSerializer

`ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)`

Metode ini hanya untuk Newtonsoft.Json pengguna. Berikut adalah sampel untuk menggunakan penamaan kasus unta:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();

`ServiceManagerOptions.JsonSerializerSettings` (Tidak digunakan lagi)

Metode ini hanya berlaku untuk jenis transportasi sementara. Jangan gunakan ini.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

Serialisasi Paket Pesan

Anda perlu menginstal Microsoft.AspNetCore.SignalR.Protocols.MessagePack paket.

Untuk menambahkan protokol MessagePack berdampingan dengan protokol JSON default:

var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());

Untuk sepenuhnya mengontrol protokol hub, Anda dapat menggunakan
```
    var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());
```
WithHubProtocols pertama-tama hapus protokol yang ada, lalu tambahkan protokol baru. Anda juga dapat menggunakan metode ini untuk menghapus protokol JSON dan hanya menggunakan MessagePack.

Untuk mode sementara, secara default sisi layanan mengonversi payload JSON ke payload MessagePack dan ini adalah cara lama untuk mendukung MessagePack. Namun, kami sarankan Anda untuk menambahkan protokol hub MessagePack secara eksplisit karena cara warisan mungkin tidak berfungsi seperti yang Anda harapkan.

Permintaan HTTP mencoba kembali

Untuk mode sementara, SDK ini menyediakan kemampuan untuk mengirim ulang permintaan secara otomatis saat kesalahan sementara terjadi, selama permintaannya idempogen. Untuk mengaktifkan kemampuan ini, Anda dapat menggunakan ServiceManagerOptions.RetryOptions properti .

Secara khusus, jenis permintaan berikut dicoba kembali:

Untuk permintaan pesan yang mengirim pesan ke klien SignalR, SDK mencoba kembali permintaan jika kode status respons HTTP lebih besar dari 500. Ketika kode respons HTTP sama dengan 500, kode tersebut mungkin menunjukkan batas waktu di sisi layanan, dan mencoba kembali permintaan dapat mengakibatkan pesan duplikat.
Untuk jenis permintaan lain, seperti menambahkan koneksi ke grup, SDK mencoba kembali permintaan dalam kondisi berikut:
1. Kode status respons HTTP berada dalam rentang 5xx, atau waktu permintaan habis dengan kode status 408 (Batas Waktu Permintaan).
2. Waktu permintaan habis dengan durasi lebih lama dari panjang batas waktu yang dikonfigurasi dalam ServiceManagerOptions.HttpClientTimeout.

SDK hanya dapat mencoba kembali permintaan idempotensi, yang merupakan permintaan yang tidak memiliki efek lain jika diulang. Jika permintaan Anda tidak idempotensi, Anda mungkin perlu menangani percobaan ulang secara manual.

Langkah berikutnya

Dalam artikel ini, Anda mempelajari cara menggunakan SignalR Service di aplikasi Anda. Periksa artikel berikut untuk mempelajari selengkapnya tentang SignalR Service.

Internal Azure SignalR Service

Mulai cepat: Membuat ruang obrolan dengan menggunakan SignalR Service

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-12-12