Pustaka klien Azure Web PubSub untuk .NET

Nota

Detail tentang istilah yang digunakan di sini dijelaskan dalam artikel konsep utama .

SDK sisi klien bertujuan untuk mempercepat alur kerja pengembang; lebih spesifik,

• menyederhanakan pengelolaan koneksi klien
• menyederhanakan pengiriman pesan di antara klien
• secara otomatis mencoba kembali setelah penurunan koneksi klien yang tidak diinginkan
• dengan andal mengirimkan pesan dalam jumlah dan secara berurutan setelah pulih dari penurunan koneksi

Seperti yang ditunjukkan dalam diagram, klien Anda membuat koneksi WebSocket dengan sumber daya Web PubSub Anda.

Memulai Langkah Pertama

Pasang paketnya

Instal pustaka klien dari NuGet:

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

Prasyarat

• Langganan Azure
• Instans Web PubSub yang ada

Mengautentikasi klien

Klien menggunakan Client Access URL untuk menyambungkan dan mengautentikasi dengan layanan. Client Access URL mengikuti pola sebagai wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Ada beberapa cara untuk mendapatkan Client Access URL. Sebagai permulaan cepat, Anda dapat menyalin dan menempel dari portal Azure, dan untuk produksi, Anda biasanya memerlukan server negosiasi untuk menghasilkan Client Access URL. Lihat detailnya.

Menggunakan URL Akses Klien dari portal Microsoft Azure

Sebagai mulai cepat, Anda dapat membuka portal Microsoft Azure dan menyalin URL Akses Klien dari bilah Kunci .

Seperti yang ditunjukkan dalam diagram, klien diberikan izin untuk mengirim pesan ke grup tertentu dan bergabung dengan grup tertentu. Pelajari selengkapnya tentang izin klien, lihat izin.

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

Menggunakan server negosiasi untuk menghasilkan Client Access URL

Dalam produksi, klien biasanya mengambil Client Access URL dari server negosiasi. Server menyimpan connection string dan menghasilkan Client Access URL melalui WebPubSubServiceClient. Sebagai sampel, cuplikan kode hanya menunjukkan cara menghasilkan Client Access URL dalam satu proses.

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

Fitur untuk membedakan WebPubSubClient dan WebPubSubServiceClient.

Nama Kelas	WebPubSubClient	WebPubSubServiceClient
Nama Paket NuGet	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
Features	Digunakan di sisi klien. Terbitkan pesan dan berlangganan pesan.	Digunakan di sisi server. Membuat Uri Akses Klien dan mengelola klien

Contoh

Mengonsumsi pesan dari server dan grup

Seorang klien dapat menambahkan panggilan balik untuk memproses pesan dari server dan grup. Perhatikan, klien hanya dapat menerima pesan grup dari grup yang telah diikutinya.

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

Menambahkan panggilan balik untuk peristiwa connected, disconnected, dan stopped

Saat koneksi klien tersambung ke layanan, peristiwa connected dipicu begitu menerima pesan terhubung dari layanan.

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

Ketika koneksi klien terputus dan gagal pulih, kejadian disconnected dipicu.

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

Ketika klien dihentikan, yang berarti koneksi klien terputus dan klien berhenti mencoba menyambungkan kembali, stopped peristiwa dipicu. Ini biasanya terjadi setelah dipanggil client.StopAsync() , atau dinonaktifkan AutoReconnect. Jika Anda ingin menghidupkan ulang klien, Anda dapat memanggil client.StartAsync() dalam acara Stopped.

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

Bergabung kembali secara otomatis ke grup dan menangani kegagalan bergabung kembali

Ketika koneksi klien terputus dan gagal pulih, semua konteks grup dibersihkan di sisi layanan. Ini berarti ketika klien terhubung kembali, perlu bergabung lagi dengan grup. Secara bawaan, opsi klien AutoRejoinGroups diaktifkan. Namun, fitur ini memiliki batasan. Klien hanya dapat bergabung kembali dengan grup yang awalnya bergabung oleh klien dan bukan yang bergabung oleh server. Dan operasi bergabung kembali dengan grup mungkin gagal karena berbagai alasan, misalnya, klien tidak memiliki hak untuk bergabung dengan grup. Dalam kasus seperti itu, pengguna perlu menambahkan panggilan balik untuk menangani kegagalan tersebut.

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

Operasi dan coba lagi

Secara default, operasi seperti client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() memiliki tiga percobaan ulang. Anda dapat menggunakan WebPubSubClientOptions.MessageRetryOptions untuk mengubah. Jika semua percobaan ulang gagal, kesalahan akan muncul. Anda dapat terus mencoba kembali dengan meneruskan hal yang sama ackId seperti percobaan ulang sebelumnya, sehingga layanan dapat membantu mendeduplikasi operasi dengan yang sama ackId.

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

Troubleshooting

Aktifkan log

Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.

export AZURE_LOG_LEVEL=verbose

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Pelacakan Langsung

Gunakan alat Live Trace dari portal Microsoft Azure untuk memeriksa lalu lintas pesan langsung melalui sumber daya Web PubSub Anda.