Azure Web PubSub client library for .NET

‏‫ملاحظة‬

تفاصيل المصطلحات المستخدمة هنا موصوفة في مقال المفاهيم الرئيسية .

تهدف حزمة تطوير التطبيقات على جانب العميل إلى تسريع سير عمل المطور؛ وبشكل أكثر تحديدا،

• يبسط إدارة اتصالات العملاء
• يبسط إرسال الرسائل بين العملاء
• تعيد المحاولات تلقائيا بعد انقطاعات الاتصال غير المقصودة بالعميل
• يقوم بتوصيل الرسائل بشكل موثوق بالعدد والترتيب بعد التعافي من انقطاعات الاتصال

كما هو موضح في الرسم التوضيحي، يقوم عملاؤك بإنشاء اتصالات WebSocket مع مورد Web PubSub الخاص بك.

الشروع

تثبيت الحزمة

تثبيت مكتبة العميل من NuGet:

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

المتطلبات المسبقه

• اشتراك Azure
• نسخة ويب PubSub موجودة

مصادقة العميل

يستخدم العميل A Client Access URL للاتصال والمصادقة مع الخدمة. Client Access URL تتبع النمط ك wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. هناك عدة طرق للحصول على .Client Access URL كبداية سريعة، يمكنك النسخ واللصق من بوابة Azure، وللإنتاج، عادة تحتاج إلى خادم تفاوض لتوليد Client Access URL. انظر التفاصيل.

استخدام رابط الوصول إلى العميل من بوابة Azure

كبداية سريعة، يمكنك الذهاب إلى بوابة Azure ونسخ رابط الوصول إلى العميل من Keys Blade.

كما هو موضح في الرسم التوضيحي، يمنح العميل إذن إرسال رسائل إلى مجموعات محددة والانضمام إلى مجموعات محددة. تعرف أكثر على إذن العميل، راجع الأصوات.

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

استخدم خادم التفاوض لتوليد الملف Client Access URL

في الإنتاج، عادة ما يجلب العميل الرسائل Client Access URL من خادم التفاوض. الخادم يحتفظ ب و connection string يولد ال Client Access URL through WebPubSubServiceClient. كعينة، يوضح مقتطف الكود فقط كيفية توليد Client Access URL عملية واحدة داخل المستخدم.

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 بين و WebPubSubServiceClient.

اسم الفئة	WebPubSubClient	WebPubSubServiceClient
اسم حزمة NuGet	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
الميزات	يستخدم في جانب العميل. انشر الرسائل واشترك فيها.	أستخدم على جانب الخادم. توليد رابط الوصول إلى العميل وإدارة العملاء

الأمثلة

استهلاك الرسائل من الخادم والمجموعات

يمكن للعميل إضافة مكالمات لاستهلاك الرسائل من الخادم والمجموعات. ملاحظة، يمكن للعملاء فقط استقبال رسائل المجموعة التي انضموا إليها.

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، و stopped الأحداث

عندما يتم توصيل اتصال العميل بالخدمة، يتم تفعيل الحدث connected بمجرد استلام الرسالة المتصلة من الخدمة.

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

عندما يتم فصل اتصال العميل ويفشل في الاستعادة، يتم تفعيل الحدث disconnected .

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

عندما يتم إيقاف عميل، مما يعني أن الاتصال بالعميل مقطع ويتوقف عن محاولة إعادة الاتصال، يتم تفعيل الحدث stopped . عادة ما يحدث هذا بعد client.StopAsync() استدعاء أو تعطيل AutoReconnect. إذا أردت إعادة تشغيل العميل، يمكنك الاتصال client.StartAsync() بالحدث Stopped .

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

إعادة الانضمام التلقائي للمجموعات والتعامل مع فشل إعادة الانضمام

عندما ينقطع اتصال العميل ويفشل في الاستعادة، يتم تنظيف جميع سياقات المجموعة من جانب الخدمة. هذا يعني أنه عندما يعيد العميل الاتصال، يحتاج إلى الانضمام مجددا إلى المجموعات. افتراضيا، الخيارات المفعلة AutoRejoinGroups للعميل. ومع ذلك، لهذه الميزة حدود. يمكن للعميل فقط إعادة الانضمام إلى المجموعات التي انضم إليها العميل في الأصل بدلا من جانب الخادم. وقد تفشل عمليات إعادة الانضمام لمجموعات لأسباب مختلفة، على سبيل المثال، العميل لا يملك إذن للانضمام إلى مجموعات. في مثل هذه الحالات، يحتاج المستخدمون إلى إضافة استدعاء للتعامل مع هذا الفشل.

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

التشغيل وإعادة المحاولة

افتراضيا، العملية مثل client.JoinGroupAsync()، client.LeaveGroupAsync()، client.SendToGroupAsync()، client.SendEventAsync() لها ثلاث تكرارات. يمكنك استخدامها WebPubSubClientOptions.MessageRetryOptions للتغيير. إذا فشلت جميع المحاولات، يتم رمي خطأ. يمكنك الاستمرار في إعادة المحاولة بتمرير نفس ackId المحاولات السابقة، وبالتالي يمكن للخدمة أن تساعد في إزالة تكرار العملية بنفس 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);
    }
}

استكشاف الأخطاء وإصلاحها

تمكين السجلات

يمكنك تعيين متغير البيئة التالي للحصول على سجلات التصحيح عند استخدام هذه المكتبة.

export AZURE_LOG_LEVEL=verbose

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

لايف تريس

استخدم أداة Live Trace من بوابة Azure لفحص حركة الرسائل الحية عبر مورد Web PubSub الخاص بك.