البرنامج التعليمي: الكشف عن خدمة WCF REST المحلية للعميل الخارجي باستخدام Azure WCF Relay

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

بعد العمل من خلال تسلسل الأقسام في هذا البرنامج التعليمي، سيكون لديك خدمة قيد التشغيل. سيكون لديك أيضًا عميل يمكنه استدعاء عمليات الخدمة.

تقوم بالمهام التالية في هذا البرنامج التعليمي:

• قم بتثبيت المتطلبات الأساسية لهذا البرنامج التعليمي.
• قم بإنشاء مساحة اسم الترحيل.
• قم بإنشاء عقد خدمة WCF.
• تنفيذ عقد WCF.
• استضافة وتشغيل خدمة WCF للتسجيل في خدمة الترحيل.
• قم بإنشاء عميل WCF لعقد الخدمة.
• تكوين عميل WCF.
• تنفيذ عميل WCF.
• قم بتشغيل التطبيقات.

المتطلبات الأساسية

لاستكمال هذا البرنامج التعليمي، ستحتاج إلى المتطلبات الأساسية التالية:

• اشتراك Azure. إذا لم يكن لديك حساب، فأنشئ حسابًا مجانيًّا قبل أن تبدأ.
• ⁧Visual Studio 2015⁧ أو أحدث. تستخدم الأمثلة في هذا البرنامج التعليمي Visual Studio 2019.
• Azure SDK for .NET. قم بتثبيته من صفحة تنزيلات SDK.

قم بإنشاء مساحة اسم الترحيل

تتمثل الخطوة الأولى في إنشاء مساحة اسم، والحصول على مفتاح توقيع الوصول المشترك (SAS). توفر مساحة الاسم حدود التطبيق لكل تطبيق يتم عرضه من خلال خدمة الترحيل. يتم إنشاء مفتاح SAS تلقائيًّا بواسطة النظام عند إنشاء مساحة اسم خدمة. توفر مجموعة مساحة اسم الخدمة ومفتاح SAS بيانات اعتماد Azure لمصادقة الوصول إلى أحد التطبيقات.

1. تسجيل الدخول إلى ⁧⁩مدخل Microsoft Azure⁧⁩.

2. حدد كل الخدمات في القائمة اليسرى. حدد Integration، وابحث عن Relays، وحرك الماوس فوق Relays، ثم حدد Create.

   

3. في صفحة إنشاء مساحة اسم ، اتبع الخطوات التالية:

   1. بالنسبة إلى Subscription، اختر اشتراك Azure لإنشاءnamespace.

   2. بالنسبة لـ "مجموعة الموارد"، اختر مجموعة موارد موجودة حيث توجد namespace، أو إنشاء مجموعة موارد جديدة.

   3. أدخل اسما لمساحة اسم الترحيل.

   4. حدد المنطقة التي يجب استضافة مساحة الاسم فيها.

   5. حدد Review + create من أسفل الصفحة.

      

   6. في صفحة مراجعة+ إنشاء حدد إنشاء.

   7. بعد بضع دقائق، سترى صفحة Relay لمساحة الاسم.

      

الحصول على بيانات اعتماد الإدارة

1. في صفحة Relay ، حدد Shared access policies في القائمة اليسرى. `

2. في إطارShared access policies، حدد RootManageSharedAccessKey.

3. في إطار سياسةSAS: RootManageSharedAccessKey، حدد زر نسخ سلسلة الاتصال الأساسية. يقوم هذا الإجراء بنسخ سلسلة الاتصال إلى الحافظة لاستخدامها لاحقاً. لصق هذه القيمة في المفكرة أو بعض المواقع المؤقتة الأخرى.

4. كرر الخطوة السابقة، وهي نسخ قيمة المفتاح الأساسي ولصقها إلى موقع مؤقت للاستخدام لاحقاً.

   

تحديد عقد خدمة WCF

يحدد عقد الخدمة العمليات التي تدعمها الخدمة. العمليات هي طرق أو وظائف خدمة الويب. يتم إنشاء العقود عن طريق تحديد واجهة C ++ أو C # أو Visual Basic. تتوافق كل طريقة في الواجهة مع عملية خدمة محددة. يجب أن يتم تطبيق السمة ServiceContractAttribute على كل واجهة، ويجب أن يتم تطبيق السمة OperationContractAttribute على كل عملية. إذا كانت إحدى الطرق في واجهة بها السمة ServiceContractAttributeلا تحتوي على السمةOperationContractAttribute، فلن يتم كشف هذه الطريقة. يتم توفير التعليمة البرمجية لهذه المهام في المثال التالي للإجراء. لإجراء مناقشة أكبر حول العقود والخدمات، راجع تصميم الخدمات وتنفيذها.

قم بإنشاء عقد ترحيل بواجهة

1. ابدأ تشغيل Microsoft Visual Studio كمسؤول. للقيام بذلك، انقر بزر الماوس الأيمن فوق التعليمة البرمجية لبرنامج Visual Studio، وحدد Run as administrator.

2. في Visual Studio، حدد Create a new project.

3. في Create a new project, اختر Console App (.NET Framework) for C# and حدد Next.

4. قم بتسمية المشروع EchoService وحدد Create.

   

5. في Solution Explorer، انقر بزر الماوس الأيمن فوق المشروع وحدد Manage NuGet Packages. في NuGet Package Manager، حدد Browse، ثم ابحث عن واختر WindowsAzure.ServiceBus. حدد Install، واقبل شروط الاستخدام.

   

   تضيف هذه الحزمة تلقائيًّا مراجع إلى مكتبات Service Bus وWCF System.ServiceModel. System.ServiceModel هي مساحة الاسم التي تمكنك من الوصول برمجيًّا إلى الميزات الأساسية لـ WCF. يستخدم ناقل الخدمة العديد من كائنات وسمات WCF لتحديد عقود الخدمة.

6. أضف عبارات using التالية أعلى Program.cs:

   using System.ServiceModel;
   using Microsoft.ServiceBus;
   

7. غيّر اسم مساحة الاسم من اسمها الافتراضي EchoService إلى Microsoft.ServiceBus.Samples.

   هام

   يستخدم هذا البرنامج التعليمي مساحة الاسم C # Microsoft.ServiceBus.Samples وهي مساحة الاسم للنوع المدار بموجب عقد والمستخدم في ملف التكوين في قسم تكوين عميل WCF. يمكنك تحديد أي مساحة اسم تريدها عند إنشاء هذه العينة. ومع ذلك، لن يعمل البرنامج التعليمي إلا إذا قمت بتعديل مساحات أسماء العقد والخدمة وفقًا لذلك، في ملف تكوين التطبيق. يجب أن تكون مساحة الاسم المحددة في ملف App.config هي نفسها مساحة الاسم المحددة في ملفات C #.

8. بعد إعلان مساحة الاسم Microsoft.ServiceBus.Samples مباشرةً، ولكن ضمن مساحة الاسم، حدد واجهة جديدة باسم IEchoContractوطبق السمةServiceContractAttribute على الواجهة بقيمة مساحة الاسمhttps://samples.microsoft.com/ServiceModel/Relay/. ألصق التعليمة البرمجية التالية بعد إعلان مساحة الاسم:

   [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
   public interface IEchoContract
   {
   }
   

   تختلف قيمة مساحة الاسم عن مساحة الاسم التي تستخدمها في نطاق التعليمة البرمجية الخاصة بك. بدلًا من ذلك، يتم استخدام قيمة مساحة الاسم كمعرف فريد لهذا العقد. يؤدي تحديد مساحة الاسم بشكل صريح إلى منع إضافة قيمة مساحة الاسم الافتراضية إلى اسم العقد.

   ملاحظة

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

9. في واجهة IEchoContract، أعلن عن طريقة للعملية الواحدة التي يعرضها العقد IEchoContract في الواجهة وقم بتطبيق سمة OperationContractAttribute على الطريقة التي تريد عرضها كجزء من WCF العام عقد الترحيل على النحو التالي:

   [OperationContract]
   string Echo(string text);
   

10. مباشرة بعد تعريف الواجهة IEchoContract، قم بتعريف القناة التي ترث من كل من IEchoContract وكذلك إلى واجهة IClientChannel، كما هو موضح هنا:

    public interface IEchoChannel : IEchoContract, IClientChannel { }
    

    القناة هي كائن WCF الذي من خلاله يقوم المضيف والعميل بتمرير المعلومات لبعضهما البعض. لاحقًا، ستكتب تعليمة برمجية على القناة لترديد المعلومات بين التطبيقين.

11. حدد Build>إنشاء حل أو حدد Ctrl + Shift + B لتأكيد دقة عملك حتى الآن.

مثال على عقد WCF

تُظهر التعليمة البرمجية التالية واجهة أساسية تحدد عقد WCF Relay.

using System;
using System.ServiceModel;

namespace Microsoft.ServiceBus.Samples
{
    [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
    public interface IEchoContract
    {
        [OperationContract]
        String Echo(string text);
    }

    public interface IEchoChannel : IEchoContract, IClientChannel { }

    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

الآن بعد أن تم إنشاء الواجهة، يمكنك تنفيذ الواجهة.

تنفيذ عقد WCF

يتطلب إنشاء Azure Relay أن تقوم أولًا بإنشاء العقد باستخدام واجهة. لمزيد من المعلومات حول إنشاء الواجهة، راجع القسم السابق. الإجراء التالي يطبق الواجهة. تتضمن هذه المهمة إنشاء فئة باسم EchoService تنفذ الواجهة IEchoContract المعرفة من قِبل المستخدم. بعد تنفيذ الواجهة، يمكنك حينئذٍ تكوين الواجهة باستخدام ملف تكوين App.config. يحتوي ملف التكوين على المعلومات الضرورية للتطبيق. تتضمن هذه المعلومات اسم الخدمة واسم العقد ونوع البروتوكول المستخدم للتواصل مع خدمة الترحيل. يتم توفير التعليمة البرمجية المستخدمة لهذه المهام في المثال الذي يتبع الإجراء. لمزيد من المناقشة العامة حول كيفية تنفيذ عقد الخدمة، راجع Implementing Service Contracts.

1. قم بإنشاء فئة جديدة باسم EchoServicedirectly after the definition of the IEchoContract. فئة EchoService تنفذ واجهةIEchoContract.

   class EchoService : IEchoContract
   {
   }
   

   على غرار تطبيقات الواجهة الأخرى، يمكنك تنفيذ التعريف في ملف مختلف. ومع ذلك، بالنسبة لهذا البرنامج التعليمي، يوجد التنفيذ في نفس الملف، مثل تعريف الواجهة والطريقة Main().

2. قم بتطبيق سمة ServiceBehaviorAttribute على الواجهة IEchoContract. تحدد السمة اسم الخدمة ومساحة الاسم. بعد القيام بذلك، تظهر فئة EchoService على النحو التالي:

   [ServiceBehavior(Name = "EchoService", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
   class EchoService : IEchoContract
   {
   }
   

3. قم بتنفيذ الأسلوب Echo المحدد في الواجهة IEchoContract في الفئة EchoService.

   public string Echo(string text)
   {
       Console.WriteLine("Echoing: {0}", text);
       return text;
   }
   

4. حدد Build>إنشاء حل أو حدد Ctrl + Shift + B.

حدد التكوين لمضيف الخدمة

ملف التكوين مشابه لملف تكوين WCF. يتضمن اسم الخدمة ونقطة النهاية والربط. نقطة النهاية هي الموقع الذي يعرضه Azure Relay للعملاء والمضيفين للتواصل مع بعضهم البعض. الربط هو نوع البروتوكول المستخدم للتواصل. يتمثل الاختلاف الرئيسي في أن نقطة نهاية الخدمة المهيأة هذه تشير إلى ربط NetTcpRelayBinding، وهو ليس جزءًا من .NET Framework. NetTcpRelayBinding هو أحد الروابط المحددة بواسطة الخدمة.

1. في مستكشف الحلول، انقر نقرًا مزدوجًا فوق App.config لفتح الملف في محرر Visual Studio.

2. في <appSettings> العنصر ، استبدل العناصر النائبة باسم مساحة اسم Azure Relay ومفتاح SAS الذي نسخته في خطوة سابقة.

3. ضمن العلامات <system.serviceModel>، أضف عنصر <services>. يمكنك تحديد تطبيقات ترحيل متعددة في ملف تكوين واحد. ومع ذلك، يحدد هذا البرنامج التعليمي واحدًا فقط.

   <?xmlversion="1.0" encoding="utf-8"?>
   <configuration>
     <system.serviceModel>
       <services>
   
       </services>
     </system.serviceModel>
   </configuration>
   

4. داخل العنصر <services>، أضف عنصر <service> لتعريف اسم الخدمة.

   <service name="Microsoft.ServiceBus.Samples.EchoService">
   </service>
   

5. ضمن عنصر <service>، حدد موقع عقد نقطة النهاية، وكذلك نوع الربط لنقطة النهاية.

   <endpoint contract="Microsoft.ServiceBus.Samples.IEchoContract" binding="netTcpRelayBinding"/>
   

   تحدد نقطة النهاية المكان الذي سيبحث فيه العميل عن التطبيق المضيف. في وقت لاحق، يستخدم البرنامج التعليمي هذه الخطوة لإنشاء URI الذي يعرض المضيف بالكامل من خلال Azure Relay. يعلن الربط أننا نستخدم TCP كبروتوكول للتواصل مع خدمة الترحيل.

6. حدد Build>إنشاء حل أو حدد Ctrl + Shift + B لتأكيد دقة عملك حتى الآن.

مثال على تنفيذ عقد الخدمة

توضح التعليمة البرمجية التالية تنفيذ عقد الخدمة.

[ServiceBehavior(Name = "EchoService", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]

    class EchoService : IEchoContract
    {
        public string Echo(string text)
        {
            Console.WriteLine("Echoing: {0}", text);
            return text;
        }
    }

التعليمة البرمجية التالية تعرض التنسيق الأساسي لملف App.config المرتبط بمضيف الخدمة.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.serviceModel>
    <services>
      <service name="Microsoft.ServiceBus.Samples.EchoService">
        <endpoint contract="Microsoft.ServiceBus.Samples.IEchoContract" binding="netTcpRelayBinding" />
      </service>
    </services>
    <extensions>
      <bindingExtensions>
        <add name="netTcpRelayBinding"
                    type="Microsoft.ServiceBus.Configuration.NetTcpRelayBindingCollectionElement, Microsoft.ServiceBus, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </bindingExtensions>
    </extensions>
  </system.serviceModel>
</configuration>

استضافة وتشغيل خدمة WCF للتسجيل في خدمة الترحيل

توضح هذه الخطوة كيفية تشغيل خدمة Azure Relay.

قم بإنشاء بيانات اعتماد الترحيل

1. في Main()، قم بإنشاء متغيرين لتخزين مساحة الاسم ومفتاح SAS اللذين يتم قراءتهما من نافذة وحدة التحكم.

   Console.Write("Your Service Namespace: ");
   string serviceNamespace = Console.ReadLine();
   Console.Write("Your SAS key: ");
   string sasKey = Console.ReadLine();
   

   سيتم استخدام مفتاح SAS لاحقًا للوصول إلى مشروعك. يتم تمرير مساحة الاسم كمعامل إلى CreateServiceUri لإنشاء URI للخدمة.

2. باستخدام كائن TransportClientEndpointBehavior، أعلن أنك ستستخدم مفتاح SAS كنوع بيانات الاعتماد. أضف التعليمة البرمجية التالية مباشرة بعد إضافة التعليمة البرمجية في الخطوة الأخيرة.

   TransportClientEndpointBehavior sasCredential = new TransportClientEndpointBehavior();
   sasCredential.TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey", sasKey);
   

قم بإنشاء عنوان أساسي للخدمة

بعد التعليمة البرمجية التي أضفتها في القسم السابق، قم بإنشاء مثيل Uri للعنوان الأساسي للخدمة. يحدد URI نظام ناقل الخدمة ومساحة الاسم ومسار واجهة الخدمة.

Uri address = ServiceBusEnvironment.CreateServiceUri("sb", serviceNamespace, "EchoService");

القيمة "sb" هي اختصار لنظام Service Bus. يشير إلى أننا نستخدم TCP كبروتوكول. تمت الإشارة إلى هذا المخطط مسبقًا أيضًا في ملف التكوين، عندما تم تحديد NetTcpRelayBinding على أنه الربط.

بالنسبة لهذا البرنامج التعليمي، فإن URI هو sb://putServiceNamespaceHere.windows.net/EchoService.

قم بإنشاء وتكوين مضيف الخدمة

1. لا يزال العمل في Main()، اضبط وضع الاتصال علىAutoDetect.

   ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.AutoDetect;
   

   يصف وضع الاتصال البروتوكول الذي تستخدمه الخدمة للاتصال بخدمة الترحيل ؛ إما HTTP أو TCP. باستخدام الإعداد الافتراضي AutoDetect، تحاول الخدمة الاتصال بـ Azure Relay عبر TCP إذا كان متاحًا، وHTTP في حالة عدم توفر TCP. تختلف هذه النتيجة عن البروتوكول الذي تحدده الخدمة للاتصال بالعميل. يتم تحديد هذا البروتوكول من خلال الربط المستخدم. على سبيل المثال، يمكن لخدمة ما استخدام الربط BasicHttpRelayBinding، والذي يحدد أن نقطة النهاية الخاصة بها تتواصل مع العملاء عبر HTTP. يمكن أن تحدد نفس الخدمة ConnectivityMode.AutoDetect بحيث تتصل الخدمة بـ Azure Relay عبر TCP.

2. قم بإنشاء مضيف الخدمة، باستخدام URI الذي تم إنشاؤه مسبقًا في هذا القسم.

   ServiceHost host = new ServiceHost(typeof(EchoService), address);
   

   مضيف الخدمة هو كائن WCF الذي ينشئ الخدمة. هنا، تقوم بتمرير نوع الخدمة التي تريد إنشاءها، ونوع EchoService، وكذلك إلى العنوان الذي تريد عرض الخدمة عليه.

3. في الجزء العلوي من ملف Program.cs، أضف مراجع إلى System.ServiceModel.Description و Microsoft.ServiceBus.Description.

   using System.ServiceModel.Description;
   using Microsoft.ServiceBus.Description;
   

4. مرة أخرى في Main()، قم بتكوين نقطة النهاية لتمكين الوصول العام.

   IEndpointBehavior serviceRegistrySettings = new ServiceRegistrySettings(DiscoveryType.Public);
   

   تُعلم هذه الخطوة خدمة الترحيل بأنه يمكن العثور على تطبيقك بشكل عام من خلال فحص موجز Atom لمشروعك. إذا قمت بتعيين DiscoveryType على private، فلا يزال بإمكان العميل الوصول إلى الخدمة. ومع ذلك، لن تظهر الخدمة عندما تبحث في مساحة الاسم Relay. بدلاً من ذلك، سيتعين على العميل معرفة مسار نقطة النهاية مسبقًا.

5. تطبيق بيانات اعتماد الخدمة على نقاط نهاية الخدمة المحددة في ملف App.config:

   foreach (ServiceEndpoint endpoint in host.Description.Endpoints)
   {
       endpoint.Behaviors.Add(serviceRegistrySettings);
       endpoint.Behaviors.Add(sasCredential);
   }
   

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

افتح مضيف الخدمة

1. لا يزال في Main()، أضف السطر التالي لفتح الخدمة.

   host.Open();
   

2. أبلغ المستخدم أن الخدمة قيد التشغيل، واشرح كيفية إيقاف تشغيل الخدمة.

   Console.WriteLine("Service address: " + address);
   Console.WriteLine("Press [Enter] to exit");
   Console.ReadLine();
   

3. عند الانتهاء، أغلق مضيف الخدمة.

   host.Close();
   

4. حدد Ctrl + Shift + B لبناء المشروع.

مثال يستضيف خدمة في تطبيق وحدة التحكم

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

using System;
using System.ServiceModel;
using System.ServiceModel.Description;
using Microsoft.ServiceBus;
using Microsoft.ServiceBus.Description;

namespace Microsoft.ServiceBus.Samples
{
    [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
    public interface IEchoContract
    {
        [OperationContract]
        String Echo(string text);
    }

    public interface IEchoChannel : IEchoContract, IClientChannel { };

    [ServiceBehavior(Name = "EchoService", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
    class EchoService : IEchoContract
    {
        public string Echo(string text)
        {
            Console.WriteLine("Echoing: {0}", text);
            return text;
        }
    }

    class Program
    {
        static void Main(string[] args)
        {

            ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.AutoDetect;         

            Console.Write("Your Service Namespace: ");
            string serviceNamespace = Console.ReadLine();
            Console.Write("Your SAS key: ");
            string sasKey = Console.ReadLine();

           // Create the credentials object for the endpoint.
            TransportClientEndpointBehavior sasCredential = new TransportClientEndpointBehavior();
            sasCredential.TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey", sasKey);

            // Create the service URI based on the service namespace.
            Uri address = ServiceBusEnvironment.CreateServiceUri("sb", serviceNamespace, "EchoService");

            // Create the service host reading the configuration.
            ServiceHost host = new ServiceHost(typeof(EchoService), address);

            // Create the ServiceRegistrySettings behavior for the endpoint.
            IEndpointBehavior serviceRegistrySettings = new ServiceRegistrySettings(DiscoveryType.Public);

            // Add the Relay credentials to all endpoints specified in configuration.
            foreach (ServiceEndpoint endpoint in host.Description.Endpoints)
            {
                endpoint.Behaviors.Add(serviceRegistrySettings);
                endpoint.Behaviors.Add(sasCredential);
            }

            // Open the service.
            host.Open();

            Console.WriteLine("Service address: " + address);
            Console.WriteLine("Press [Enter] to exit");
            Console.ReadLine();

            // Close the service.
            host.Close();
        }
    }
}

قم بإنشاء عميل WCF لعقد الخدمة

المهمة التالية هي إنشاء تطبيق عميل وتحديد عقد الخدمة الذي ستنفذه لاحقًا. تشبه هذه الخطوات المستخدمة لإنشاء خدمة: تحديد عقد، وتحرير ملف App.config، واستخدام بيانات الاعتماد للاتصال بخدمة الترحيل، وما إلى ذلك. يتم توفير التعليمة البرمجية المستخدمة لهذه المهام في المثال التالي للإجراء.

1. إنشاء مشروع جديد في حل Visual Studio الحالي للعميل:

   1. في Solution Explorer، انقر بزر الماوس الأيمن فوق الحل الحالي (وليس المشروع)، وحدد Add>New Project.
   2. في Add a new project، حدد Console App (.NET Framework) لـ #C ثم حدد Next.
   3. اسم المشروع EchoClient وحدد Create.

2. في Solution Explorer، في مشروع EchoClient، انقر نقرًا مزدوجًا فوق Program.cs لفتح الملف في المحرر، إذا لم يكن مفتوحًا بالفعل.

3. غيّر اسم مساحة الاسم من اسمها الافتراضي EchoClient إلى Microsoft.ServiceBus.Samples.

4. قم بتثبيت حزمة Service Bus NuGet:

   1. في Solution Explorer، انقر بزر الماوس الأيمن فوق EchoClient ثم حدد Manage NuGet Packages.

   2. حدد Browse، ثم ابحث عن WindowsAzure.ServiceBus وحدده. حدد Install، واقبل شروط الاستخدام.

      

5. أضف عبارة using لمساحة الاسم System.ServiceModel في ملف Program.cs.

   using System.ServiceModel;
   

6. أضف تعريف عقد الخدمة إلى مساحة الاسم، كما هو موضح في المثال التالي. هذا التعريف مطابق للتعريف المستخدم في مشروع الخدمة. أضف هذه الشفرة أعلى مساحة الاسم Microsoft.ServiceBus.Samples.

   [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
   public interface IEchoContract
   {
       [OperationContract]
       string Echo(string text);
   }
   
   public interface IEchoChannel : IEchoContract, IClientChannel { }
   

7. حدد Ctrl + Shift + B لبناء العميل.

مثال على مشروع EchoClient

توضح التعليمة البرمجية التالية الحالة الحالية لملف Program.cs في مشروع EchoClient.

using System;
using Microsoft.ServiceBus;
using System.ServiceModel;

namespace Microsoft.ServiceBus.Samples
{

    [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
    public interface IEchoContract
    {
        [OperationContract]
        string Echo(string text);
    }

    public interface IEchoChannel : IEchoContract, IClientChannel { }


    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

تكوين عميل WCF

في هذه الخطوة، تقوم بإنشاء ملف App.config لتطبيق عميل أساسي يصل إلى الخدمة التي تم إنشاؤها مسبقًا في هذا البرنامج التعليمي. يعرّف ملف App.config هذا العقد والربط واسم نقطة النهاية. يتم توفير التعليمة البرمجية المستخدمة لهذه المهام في المثال التالي للإجراء.

1. في Solution Explorer، في مشروع EchoClient، انقر نقرًا مزدوجًا فوق App.config لفتح الملف في محرر Visual Studio.

2. في عنصر <appSettings>، استبدل العناصر النائبة باسم مساحة اسم الخدمة ومفتاح SAS الذي نسخته في خطوة سابقة.

3. داخل العنصر system.serviceModel، أضف عنصر <client>.

   <?xmlversion="1.0" encoding="utf-8"?>
   <configuration>
     <system.serviceModel>
       <client>
       </client>
     </system.serviceModel>
   </configuration>
   

   توضح هذه التعليمة البرمجية أنك تقوم بتعريف تطبيق عميل على نمط WCF.

4. ضمن عنصر client، حدد الاسم والعقد ونوع الربط لنقطة النهاية.

   <endpoint name="RelayEndpoint"
                   contract="Microsoft.ServiceBus.Samples.IEchoContract"
                   binding="netTcpRelayBinding"/>
   

   تحدد هذه التعليمة البرمجية اسم نقطة النهاية. كما تحدد العقد المحدد في الخدمة وحقيقة أن تطبيق العميل يستخدم TCP للتواصل مع Azure Relay. يتم استخدام اسم نقطة النهاية في الخطوة التالية لربط تكوين نقطة النهاية مع URI للخدمة.

5. حدد File>Save All.

مثال على ملف App.config

التعليمة البرمجية التالية تعرض ملف App.config لعميل Echo.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.serviceModel>
    <client>
      <endpoint name="RelayEndpoint"
                      contract="Microsoft.ServiceBus.Samples.IEchoContract"
                      binding="netTcpRelayBinding"/>
    </client>
    <extensions>
      <bindingExtensions>
        <add name="netTcpRelayBinding"
                    type="Microsoft.ServiceBus.Configuration.NetTcpRelayBindingCollectionElement, Microsoft.ServiceBus, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </bindingExtensions>
    </extensions>
  </system.serviceModel>
</configuration>

تنفيذ عميل WCF

في هذا القسم، تقوم بتنفيذ تطبيق عميل أساسي يصل إلى الخدمة التي قمت بإنشائها مسبقًا في هذا البرنامج التعليمي. على غرار الخدمة، يقوم العميل بالعديد من العمليات نفسها للوصول إلى Azure Relay:

• يضبط وضع الاتصال.
• ينشئ URI الذي يحدد موقع الخدمة المضيفة.
• يحدد بيانات اعتماد الأمان.
• يطبق بيانات الاعتماد على الاتصال.
• يفتح الاتصال.
• يؤدي المهام الخاصة بالتطبيق.
• يغلق الاتصال.

ومع ذلك، فإن أحد الاختلافات الرئيسية هو أن تطبيق العميل يستخدم قناة للاتصال بخدمة الترحيل. تستخدم الخدمة اتصالًا بـ ServiceHost. يتم توفير التعليمة البرمجية المستخدمة لهذه المهام في المثال التالي للإجراء.

تنفيذ تطبيق العميل

1. اضبط وضع الاتصال على AutoDetect. أضف التعليمة البرمجية التالية داخل طريقة Main()للتطبيق EchoClient.

   ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.AutoDetect;
   

2. حدد المتغيرات للاحتفاظ بقيم مساحة اسم الخدمة ومفتاح SAS المقروءة من وحدة التحكم.

   Console.Write("Your Service Namespace: ");
   string serviceNamespace = Console.ReadLine();
   Console.Write("Your SAS Key: ");
   string sasKey = Console.ReadLine();
   

3. قم بإنشاء URI الذي يحدد موقع المضيف في مشروع Relay الخاص بك.

   Uri serviceUri = ServiceBusEnvironment.CreateServiceUri("sb", serviceNamespace, "EchoService");
   

4. قم بإنشاء كائن بيانات الاعتماد لنقطة نهاية مساحة اسم الخدمة الخاصة بك.

   TransportClientEndpointBehavior sasCredential = new TransportClientEndpointBehavior();
   sasCredential.TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey", sasKey);
   

5. قم بإنشاء مصنع القناة الذي يقوم بتحميل التكوين الموضح في ملف App.config.

   ChannelFactory<IEchoChannel> channelFactory = new ChannelFactory<IEchoChannel>("RelayEndpoint", new EndpointAddress(serviceUri));
   

   مصنع القنوات هو كائن WCF يقوم بإنشاء قناة تتواصل من خلالها الخدمة وتطبيقات العميل.

6. قم بتطبيق بيانات الاعتماد.

   channelFactory.Endpoint.Behaviors.Add(sasCredential);
   

7. قم بإنشاء وفتح القناة للخدمة.

   IEchoChannel channel = channelFactory.CreateChannel();
   channel.Open();
   

8. اكتب واجهة المستخدم الأساسية ووظائف الصدى.

   Console.WriteLine("Enter text to echo (or [Enter] to exit):");
   string input = Console.ReadLine();
   while (input != String.Empty)
   {
       try
       {
           Console.WriteLine("Server echoed: {0}", channel.Echo(input));
       }
       catch (Exception e)
       {
           Console.WriteLine("Error: " + e.Message);
       }
       input = Console.ReadLine();
   }
   

   التعليمة البرمجية تستخدم مثيل كائن القناة كوكيل للخدمة.

9. أغلق القناة وأغلق المصنع.

   channel.Close();
   channelFactory.Close();
   

التعليمة البرمجية المثال لهذا البرنامج التعليمي

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

using System;
using Microsoft.ServiceBus;
using System.ServiceModel;

namespace Microsoft.ServiceBus.Samples
{
    [ServiceContract(Name = "IEchoContract", Namespace = "https://samples.microsoft.com/ServiceModel/Relay/")]
    public interface IEchoContract
    {
        [OperationContract]
        String Echo(string text);
    }

    public interface IEchoChannel : IEchoContract, IClientChannel { }

    class Program
    {
        static void Main(string[] args)
        {
            ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.AutoDetect;


            Console.Write("Your Service Namespace: ");
            string serviceNamespace = Console.ReadLine();
            Console.Write("Your SAS Key: ");
            string sasKey = Console.ReadLine();



            Uri serviceUri = ServiceBusEnvironment.CreateServiceUri("sb", serviceNamespace, "EchoService");

            TransportClientEndpointBehavior sasCredential = new TransportClientEndpointBehavior();
            sasCredential.TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey", sasKey);

            ChannelFactory<IEchoChannel> channelFactory = new ChannelFactory<IEchoChannel>("RelayEndpoint", new EndpointAddress(serviceUri));

            channelFactory.Endpoint.Behaviors.Add(sasCredential);

            IEchoChannel channel = channelFactory.CreateChannel();
            channel.Open();

            Console.WriteLine("Enter text to echo (or [Enter] to exit):");
            string input = Console.ReadLine();
            while (input != String.Empty)
            {
                try
                {
                    Console.WriteLine("Server echoed: {0}", channel.Echo(input));
                }
                catch (Exception e)
                {
                    Console.WriteLine("Error: " + e.Message);
                }
                input = Console.ReadLine();
            }

            channel.Close();
            channelFactory.Close();

        }
    }
}

تشغيل التطبيقات

1. حدد Ctrl + Shift + B لبناء الحل. ينشئ هذا الإجراء كلًّا من مشروع العميل ومشروع الخدمة الذي أنشأته في الخطوات السابقة.

2. قبل تشغيل تطبيق العميل، يجب التأكد من تشغيل تطبيق الخدمة. في Solution Explorer، انقر بزر الماوس الأيمن فوق حل EchoService، ثم حدد Properties.

3. في Property Pages، الخصائص العامة>مشروع بدء التشغيل، ثم اختر Multiple startup projects. تأكد من ظهور EchoService أولًا في القائمة.

4. عيّن مربع Action لكل من مشروعي EchoService وEchoClient على Start.

   

5. حدد Project Dependencies. في المشاريع، حدد EchoClient. بالنسبة إلى Depends on، تأكد من تحديد EchoService.

   

6. حدد OK لإغلاق Property Pages.

7. حدد F5 لتشغيل كلا المشروعين.

8. تفتح كلتا نافذتي وحدة التحكم وتطالبك بإدخال اسم مساحة الاسم. يجب تشغيل الخدمة أولًا، لذا في نافذة وحدة التحكم EchoServiceأدخل مساحة الاسم ثم حدد إدخال.

9. بعد ذلك، تطالبك وحدة التحكم بمفتاح SAS الخاص بك. أدخل مفتاح SAS وحدد إدخال.

   فيما يلي مثال على الإخراج من نافذة وحدة التحكم. القيم هنا مجرد أمثلة.

   Your Service Namespace: myNamespace

   Your SAS Key: <SAS key value>

   يقوم تطبيق الخدمة بطباعة العنوان الذي يستمع إليه إلى نافذة وحدة التحكم، كما هو موضح في المثال التالي.

   Service address: sb://mynamespace.servicebus.windows.net/EchoService/

   Press [Enter] to exit

10. في نافذة وحدة التحكم EchoClient، أدخل نفس المعلومات التي أدخلتها مسبقًا لتطبيق الخدمة. أدخل نفس مساحة اسم الخدمة وقيم مفتاح SAS لتطبيق العميل.

11. بعد إدخال هذه القيم، يفتح العميل قناة للخدمة ويطالبك بإدخال بعض النص كما هو موضح في مثال إخراج وحدة التحكم التالي.

    Enter text to echo (or [Enter] to exit):

    أدخل نصًّا لإرساله إلى تطبيق الخدمة وحدد إدخال. يتم إرسال هذا النص إلى الخدمة من خلال عملية خدمة Echo ويظهر في نافذة وحدة التحكم بالخدمة كما في المثال التالي الناتج.

    Echoing: My sample text

    يتلقى تطبيق العميل القيمة المرجعة لعملية Echo، وهو النص الأصلي، ويطبعها في نافذة وحدة التحكم الخاصة به. النص التالي هو مثال لإخراج من نافذة وحدة تحكم العميل.

    Server echoed: My sample text

12. يمكنك الاستمرار في إرسال الرسائل النصية من العميل إلى الخدمة بهذه الطريقة. عند الانتهاء، حدد إدخال في نوافذ العميل ووحدة تحكم الخدمة لإنهاء كلا التطبيقين.

الخطوات التالية

تقدم إلى البرنامج التعليمي التالي:

عرض خدمة WCF REST المحلية لعميل خارج شبكتك