.NET için Azure Web PubSub istemci kitaplığı

Uyarı

Burada kullanılan terimlerle ilgili ayrıntılar temel kavramlar makalesinde açıklanmıştır.

İstemci tarafı SDK'sı, geliştiricinin iş akışını hızlandırmayı amaçlar; daha ayrıntılı olarak,

• istemci bağlantılarını yönetmeyi kolaylaştırır
• istemciler arasında ileti göndermeyi kolaylaştırır
• İstemci bağlantısının istenmeyen kesilmelerinden sonra otomatik olarak yeniden denenir.
• bağlantı kesintisine uğradıktan sonra iletileri sayıca ve sırayla güvenilir bir şekilde teslim eder.

Diyagramda gösterildiği gibi, istemcileriniz Web PubSub kaynağınızla WebSocket bağlantıları kurar.

Başlangıç Yapmak

Paketi yükle

NuGet'ten istemci kitaplığını yükleyin:

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

Önkoşullar

• Azure aboneliği
• Mevcut bir Web PubSub örneği

İstemcinin kimliğini doğrulama

İstemci, hizmete bağlanmak ve hizmetle kimlik doğrulaması yapmak için bir Client Access URL kullanır. Client Access URL wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> desenini takip eder. Client Access URL almanın birden çok yolu vardır. Hızlı bir başlangıç olarak, Azure portalından kopyalayıp yapıştırabilirsiniz ve üretim için genellikle Client Access URL oluşturmak amacıyla bir müzakere sunucusuna ihtiyacınız vardır. Ayrıntılara bakın.

Azure portalından İstemci Erişimi URL'sini kullanma

Hızlı bir başlangıç olarak Azure portalına gidebilir ve İstemci Erişimi URL'siniAnahtarlar panelinden kopyalayabilirsiniz.

Diyagramda gösterildiği gibi, istemciye belirli gruplara ileti gönderme ve belirli grupları birleştirme izni verilir. İstemci izinleri hakkında detaylı bilgi almak için izinler bölümüne bakın.

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

Anlaşma sunucusunu kullanarak Client Access URL oluştur.

Üretimde istemci genellikle bir müzakere sunucusundan Client Access URL öğesini getirir. Sunucu connection string öğesini tutar ve WebPubSubServiceClient aracılığıyla Client Access URL öğesini oluşturur. Örnek olarak, kod parçacığı yalnızca tek bir işlem içinde Client Access URL oluşturulacağını nasıl göstereceğini demonstre eder.

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

WebPubSubClient ve WebPubSubServiceClient arasındaki farkları belirten özellikler.

Sınıf Adı	WebPubSubClient	WebPubSubServiceClient
NuGet Paket Adı	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
Özellikler	İstemci tarafında kullanılır. İletileri yayımlayın ve iletilere abone olun.	Sunucu tarafında kullanılır. İstemci Erişim Uri'si oluşturma ve istemcileri yönetme

Örnekler

Sunucudan ve gruplardan gelen mesajları tüket

İstemci, sunucudan ve gruplardan gelen iletileri kullanmak için geri çağırmalar ekleyebilir. İstemcilerin yalnızca katıldığı grup iletilerini alabileceğini unutmayın.

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;
};

connected, disconnected ve stopped olayları için geri çağırmalar ekleyin

Hizmete bir istemci bağlantısı bağlandığında, connected olayı, hizmetten bağlı mesajı aldıktan sonra tetiklenir.

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

İstemci bağlantısı kesildiğinde ve kurtarılamadığında disconnected olayı tetiklenir.

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

Bir istemci durdurulduğunda, yani istemci bağlantısı kesildiğinde ve istemci yeniden bağlanmayı denemeyi durdurduğunda, stopped olayı tetiklenir. Bu genellikle client.StopAsync() çağrıldıktan veya AutoReconnect devre dışı bırakıldıktan sonra gerçekleşir. İstemciyi yeniden başlatmak istiyorsanız, client.StartAsync() fonksiyonunu Stopped olayında çağırabilirsiniz.

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

Gruplara otomatik yeniden katılma ve yeniden katılma hatasını işleme

İstemci bağlantısı kesildiğinde ve iyileşemezse, hizmet tarafında tüm grup bağlamları temizlenir. Bu, istemci yeniden bağlandığında gruplara yeniden katılması gerektiği anlamına gelir. Varsayılan olarak, istemci AutoRejoinGroups seçeneklerini etkinleştirdi. Ancak bu özelliğin sınırlamaları vardır. İstemci, başlangıçta sunucu tarafından değil de istemci tarafından katılmış gruplara yeniden bağlanabilir. Örneğin istemcinin gruplara katılma izni olmaması gibi çeşitli nedenlerle grup işlemlerine yeniden katılma işlemi başarısız olabilir. Böyle durumlarda, kullanıcıların bu tür hataları işlemek için bir geri çağırma eklemesi gerekir.

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

İşlem ve yeniden deneme

Varsayılan olarak, client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() gibi işlemler üç kez yeniden denenir. WebPubSubClientOptions.MessageRetryOptions kullanarak değiştirebilirsiniz. Tüm yeniden denemeler başarısız olursa bir hata oluşur. Önceki yeniden denemelerdekiyle aynı ackId'u sunarak yeniden denemeye devam edebilirsiniz, böylece hizmet, işlemi aynı ackId kullanarak yinelenenleri ortadan kaldırmaya yardımcı olabilir.

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

Sorun giderme

Günlükleri etkinleştirme

Bu kitaplığı kullanırken hata ayıklama günlüklerini almak için aşağıdaki ortam değişkenini ayarlayabilirsiniz.

export AZURE_LOG_LEVEL=verbose

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Canlı İzleme

Web PubSub kaynağınız aracılığıyla canlı ileti trafiğini incelemek için Azure portalındaki Canlı İzleme aracını kullanın.